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

package/dist/hosts/local-host.js

@@ -0,0 +1,356 @@
+// localHost: run an instance of a run on this machine. Default mode: a systemd transient service created
+// through the system manager, running as an unprivileged user with KillMode=control-group, so stopping or restarting
+// it kills every command the instance started, pi's detached ones included. Development mode ("child"): a detached
+// child process, without that guarantee (commands of a crashed child can outlive it).
+//
+// Root: every archil verb needs root (client 0.8.42), so the instance runs them through `sudo -n`, as the claim does;
+// the instance and the agent's tools run as `user`. The mount goes through `bin/archil-scoped`, which starts the FUSE
+// daemon in its own scope (`<unit>-fuse-<n>.scope`), outside the instance's control group: a restart in place finds
+// the claim still held. The mount token is reusable for a day, so no process of the run's user may read it:
+// it reaches the instance on stdin from a root-only file (/run/pi-durable-disk/<unit>.mount-token) that systemd opens
+// as root; the file is replaced by an empty one once the unit started (the instance's fd keeps the token, a restart in
+// place reads nothing and reuses its live mount), the instance closes its stdin after reading, and stop removes it.
+// The token is never in argv, the environment, a systemd credential directory or anything the run's user can open.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ARCHIL_SCOPED, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
+import { EXIT_FENCED, EXIT_HELD, PdaError } from "../errors.js";
+import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
+export class LocalHostError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+const SAFE_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+const TOKEN_DIR = "/run/pi-durable-disk";
+const SYSTEMCTL = "/usr/bin/systemctl";
+const SYSTEMD_RUN = "/usr/bin/systemd-run";
+const ARCHIL = "/usr/bin/archil";
+const UNIT_SAFE = /^[A-Za-z0-9:_.-]{1,200}$/;
+const POLITE_UNMOUNT_MS = 10_000;
+const STAT = "/usr/bin/stat";
+const FUSERMOUNT = "/usr/bin/fusermount";
+const UMOUNT = "/usr/bin/umount";
+/** How long a stat of the mountpoint may take before its daemon counts as alive but stuck (never removed). */
+const STAT_TIMEOUT_MS = 3_000;
+/** EX_DATAERR: a store behind its seal or a bad run.json (run.ts names it EXIT_DATAERR). */
+const EXIT_DATAERR = 65;
+/** EX_SOFTWARE: the store's head is unreadable (pi's schema moved); run.json says failed, STORE_HEAD_UNREADABLE. */
+const EXIT_SOFTWARE = 70;
+/** Exits a restart cannot fix: 65 data error, 70 store head unreadable, 75 fenced, 76 held. */
+export const TERMINAL_EXITS = [EXIT_DATAERR, EXIT_SOFTWARE, EXIT_FENCED, EXIT_HELD];
+// The package's own CLI, with the extension this module has: `.ts` from a checkout, `.js` once built.
+const CLI = fileURLToPath(new URL(`../cli${extname(import.meta.url)}`, import.meta.url));
+/** Minimal environment, a timeout that settles even if a grandchild keeps the pipes, and the input on stdin. */
+export const runCommand = (argv, opts = {}) => new Promise((resolve, reject) => {
+    let stdout = "", stderr = "", settled = false;
+    const child = spawn(argv[0], argv.slice(1), { env: { PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: process.env.HOME ?? "/" }, stdio: ["pipe", "pipe", "pipe"] });
+    child.stdout.setEncoding("utf8").on("data", (c) => (stdout += c));
+    child.stderr.setEncoding("utf8").on("data", (c) => (stderr += c));
+    const done = (r) => void (settled || ((settled = true), clearTimeout(timer), resolve(r)));
+    const timer = setTimeout(() => {
+        child.kill("SIGTERM");
+        child.stdout.destroy();
+        child.stderr.destroy();
+        done({ code: null, timedOut: true, stdout, stderr });
+    }, opts.timeoutMs ?? 30_000);
+    child.on("error", (err) => void (settled || ((settled = true), clearTimeout(timer), reject(err))));
+    child.on("close", (code) => done({ code, timedOut: false, stdout, stderr }));
+    child.stdin.on("error", () => { });
+    child.stdin.end(opts.input ?? "");
+});
+export function currentBootId() {
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+}
+const firstLine = (r) => (r.stderr.trim().split("\n").at(-1) ?? "").slice(0, 300);
+const okRan = (r) => r.code === 0 && !r.timedOut;
+/** `systemctl show` output as a map. */
+export function parseShow(text) {
+    const out = {};
+    for (const line of text.split("\n")) {
+        const i = line.indexOf("=");
+        if (i > 0)
+            out[line.slice(0, i)] = line.slice(i + 1);
+    }
+    return out;
+}
+/** A unit's state as a host status: loaded and active (or restarting) is running; unloaded is gone. */
+export function unitStatus(show) {
+    if (show.LoadState === "not-found" || show.LoadState === undefined)
+        return "gone";
+    switch (show.ActiveState) {
+        case "active":
+        case "activating":
+        case "deactivating":
+        case "reloading":
+        case "refreshing":
+            return "running";
+        case "failed":
+            return "failed";
+        case "inactive":
+            return "stopped";
+        default:
+            return "unknown";
+    }
+}
+export function localHost(opts = {}) {
+    const mode = opts.mode ?? "systemd";
+    const mountRoot = opts.mountRoot ?? DEFAULT_MOUNT_ROOT;
+    const hostName = opts.hostName ?? hostname();
+    const bootId = currentBootId();
+    const exec = opts.exec ?? runCommand;
+    const isRoot = process.getuid?.() === 0;
+    const sudo = opts.sudo ?? (isRoot ? false : "/usr/bin/sudo");
+    const asRoot = (argv) => (sudo ? [sudo, "-n", ...argv] : argv);
+    const root = (argv, o) => exec(asRoot(argv), o);
+    if (isRoot && opts.user === undefined && mode === "systemd") {
+        throw new LocalHostError("INVALID_ARGUMENT", "running as root: name the unprivileged user the instance runs as (user)");
+    }
+    const user = String(opts.user ?? process.getuid?.() ?? "");
+    const group = String(opts.group ?? process.getgid?.() ?? "");
+    const command = opts.command ?? [process.execPath, CLI];
+    const archil = opts.archil ?? ARCHIL_SCOPED;
+    const stopTimeoutMs = opts.stopTimeoutMs ?? 30_000;
+    const prefix = opts.unitPrefix ?? "pda-";
+    const procMounts = opts.procMounts ?? "/proc/self/mounts";
+    const mine = (h) => h.driver === "local" && h.host === hostName;
+    const mountpointOf = (ref) => join(mountRoot, runPath(ref.id));
+    const mounted = async (mp) => (await readFile(procMounts, "utf8")).split("\n").some((l) => l.split(" ")[1] === mp);
+    const parkMs = opts.parkThresholdMs === undefined ? LOCAL_PARK_THRESHOLD_MS : opts.parkThresholdMs;
+    const drainMs = Math.max(0, stopTimeoutMs - Math.min(5_000, stopTimeoutMs / 2));
+    const runFlags = (ref) => [
+        "run", "--disk", ref.disk, "--region", ref.region, "--id", ref.id, "--mount-root", mountRoot, "--archil", archil,
+        ...(parkMs ? ["--park-threshold", `${parkMs}ms`] : []),
+        "--drain-timeout", `${Math.floor(drainMs)}ms`,
+        ...(opts.runArgs ?? []),
+    ];
+    const holderEnv = (h) => JSON.stringify(h);
+    const tokenFile = (unit) => join(TOKEN_DIR, `${unit}.mount-token`);
+    async function writeTokenFile(path, token) {
+        if (!sudo) {
+            await mkdir(TOKEN_DIR, { recursive: true, mode: 0o700 });
+            await writeFile(path, token, { mode: 0o600 });
+            return;
+        }
+        const r = await root(["/bin/sh", "-c", 'umask 077 && mkdir -p "$1" && cat > "$2"', "sh", TOKEN_DIR, path], { input: token });
+        if (!okRan(r))
+            throw new LocalHostError("START_FAILED", `cannot write the mount token file: ${firstLine(r)}`);
+    }
+    /** Replace the token file by an empty one: the started instance's open fd keeps the token, the path no longer has it. */
+    async function emptyTokenFile(path) {
+        const r = await root(["/bin/sh", "-c", 'umask 077 && : > "$1.tmp" && mv -f "$1.tmp" "$1"', "sh", path]);
+        if (!okRan(r))
+            await removeFile(path);
+    }
+    async function removeFile(path) {
+        if (!sudo)
+            return rm(path, { force: true });
+        await root(["/bin/rm", "-f", path]);
+    }
+    async function startUnit(ref, token) {
+        const unit = `${prefix}${ref.id}-${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36).padStart(2, "0")}`;
+        if (!UNIT_SAFE.test(unit))
+            throw new LocalHostError("INVALID_ARGUMENT", `unit name ${unit} is not safe`);
+        const mountpoint = mountpointOf(ref);
+        const handle = { driver: "local", mode: "systemd", host: hostName, bootId, unit, mountpoint };
+        const env = { ...opts.env, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
+        const path = tokenFile(unit);
+        await writeTokenFile(path, token);
+        let started = false;
+        try {
+            const argv = [
+                SYSTEMD_RUN,
+                `--unit=${unit}`,
+                `--description=pi-durable-disk run ${ref.id}`,
+                "--service-type=exec",
+                "--quiet",
+                "-p", "KillMode=control-group",
+                "-p", `TimeoutStopSec=${Math.max(1, Math.ceil(stopTimeoutMs / 1000))}s`,
+                ...(opts.restart === false ? [] : ["-p", "Restart=on-failure", "-p", "RestartSec=1", "-p", `RestartPreventExitStatus=${TERMINAL_EXITS.join(" ")}`]),
+                "-p", `User=${user}`,
+                "-p", `Group=${group}`,
+                "-p", `StandardInput=file:${path}`,
+                ...Object.entries(env).map(([k, v]) => `--setenv=${k}=${v}`),
+                "--",
+                ...command,
+                ...runFlags(ref),
+                "--token-stdin",
+            ];
+            const r = await root(argv, { timeoutMs: 60_000 });
+            if (!okRan(r))
+                throw new LocalHostError("START_FAILED", `systemd-run ${unit}: ${r.timedOut ? "timed out" : `exit ${r.code}`}: ${firstLine(r)}`);
+            started = true;
+            return handle;
+        }
+        finally {
+            // Type=exec: systemd-run returns after the exec, so the instance's stdin is already open on the token. The path
+            // stays (empty) because a restart in place opens it again; stop removes it.
+            await (started ? emptyTokenFile(path) : removeFile(path)).catch(() => { });
+        }
+    }
+    async function startChild(ref, token) {
+        const tag = `${prefix}${ref.id}-${Date.now().toString(36)}`;
+        const mountpoint = mountpointOf(ref);
+        const base = { driver: "local", mode: "child", host: hostName, bootId, mountpoint, tag };
+        let out = "ignore";
+        if (opts.logDir) {
+            const { openSync } = await import("node:fs");
+            out = openSync(join(opts.logDir, `${tag}.log`), "a", 0o600);
+        }
+        const env = { ...opts.env, PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: process.env.HOME ?? "/", PDA_HOLDER: holderEnv(base) };
+        const child = spawn(command[0], [...command.slice(1), ...runFlags(ref), "--token-stdin"], { detached: true, stdio: ["pipe", out, out], env });
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", (err) => reject(new LocalHostError("START_FAILED", `cannot start ${command[0]}`, { cause: err })));
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(`${token}\n`);
+        child.unref();
+        if (typeof out === "number")
+            (await import("node:fs")).closeSync(out);
+        const pid = child.pid;
+        return { ...base, pid, startTicks: procStartTicks(pid) ?? 0 };
+    }
+    /** The FUSE scopes this unit's mounts run in that are still active. */
+    async function fuseScopes(unit) {
+        const r = await exec([SYSTEMCTL, "list-units", "--all", "--plain", "--no-legend", "--type=scope", `${unit}-fuse-*`]);
+        return r.stdout
+            .split("\n")
+            .map((l) => l.trim().split(/\s+/))
+            .filter((f) => f.length >= 3 && f[2] === "active")
+            .map((f) => f[0]);
+    }
+    /** SIGKILL the unit's FUSE daemons (power-off semantics for its mount) and wait until their scopes are gone. */
+    async function killDaemons(unit) {
+        const alive = await fuseScopes(unit);
+        if (!alive.length)
+            return;
+        await root([SYSTEMCTL, "kill", "--signal=SIGKILL", ...alive]);
+        for (let i = 0; i < 50 && (await fuseScopes(unit)).length; i++)
+            await new Promise((r) => setTimeout(r, 100));
+    }
+    /**
+     * Whether the mount at `mp` is dead: its FUSE daemon is gone, so the kernel answers with ENOTCONN ("Transport endpoint
+     * is not connected"). The stat runs in a child with a timeout, so a live but stuck daemon never blocks this process; a
+     * stat that answers or does not finish is a live mount.
+     */
+    async function deadMount(mp) {
+        const r = await exec([STAT, "-c", "%i", mp], { timeoutMs: STAT_TIMEOUT_MS });
+        return !r.timedOut && r.code !== 0 && /Transport endpoint is not connected/.test(r.stderr);
+    }
+    /** Remove a dead mount: `fusermount -u`, then a lazy `umount -l`. The mount table, not an exit code, decides. */
+    async function removeDeadMount(mp) {
+        await root([FUSERMOUNT, "-u", mp]);
+        if (await mounted(mp))
+            await root([UMOUNT, "-l", mp]);
+        if (await mounted(mp))
+            throw new LocalHostError("STOP_FAILED", `${mp} is still mounted after fusermount -u and umount -l`);
+        await root(["/bin/rmdir", mp]);
+    }
+    /**
+     * Clean the run's mount after its instance is gone. With the mount in the table and this unit's FUSE scope alive:
+     * `archil unmount` (flush, check the delegation in) in a child process with a short timeout. Then this unit's FUSE
+     * scope is SIGKILLed while it is still active, whatever the mount table says: a client whose filesystem FAILED (an
+     * auth failure at a token refresh) drops its mount but keeps its process and the mountpoint's control socket, and the
+     * next mount at the path is refused for as long as it lives. The scope must be gone afterwards. Then a mount still in
+     * the table whose daemon is gone (a power off, an OOM kill, the SIGKILL) is removed. A live mount without this unit's
+     * scope is a newer instance's and is never touched; nothing here stats the mount from this process.
+     */
+    async function cleanMount(unit, mp) {
+        if ((await mounted(mp)) && (await fuseScopes(unit)).length)
+            await root([ARCHIL, "unmount", mp], { timeoutMs: POLITE_UNMOUNT_MS });
+        await killDaemons(unit);
+        const left = await fuseScopes(unit);
+        if (left.length)
+            throw new LocalHostError("STOP_FAILED", `${left.join(", ")} still active after SIGKILL`);
+        if ((await mounted(mp)) && (await deadMount(mp)))
+            await removeDeadMount(mp);
+    }
+    async function show(unit) {
+        const r = await exec([SYSTEMCTL, "show", `${unit}.service`, "--property=LoadState,ActiveState,SubState,Result,ExecMainStatus,MainPID"]);
+        return parseShow(r.stdout);
+    }
+    return {
+        hostName,
+        mountRoot,
+        start(ref, token) {
+            runPath(ref.id);
+            return mode === "systemd" ? startUnit(ref, token) : startChild(ref, token);
+        },
+        async status(h) {
+            if (!mine(h))
+                return "unknown";
+            if (h.bootId !== bootId)
+                return "gone";
+            if (h.mode === "child") {
+                const ticks = procStartTicks(Number(h.pid));
+                return ticks === null || ticks !== h.startTicks ? "stopped" : "running";
+            }
+            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
+                return "unknown";
+            return unitStatus(await show(h.unit));
+        },
+        async stop(h) {
+            if (!mine(h) || h.bootId !== bootId)
+                return;
+            if (h.mode === "child") {
+                const pid = Number(h.pid);
+                // A handle comes back from run.json with whatever was written there, and stop signals its pid as a group: only a
+                // real process, then. A pid of 1 or below names a group (`kill(-0)` is this supervisor's own, `kill(-1)` every
+                // process it may signal), and without start ticks nothing tells a reused pid from the instance.
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
+                    return;
+                const alive = () => procStartTicks(pid) === h.startTicks;
+                if (!alive())
+                    return;
+                try {
+                    process.kill(-pid, "SIGTERM");
+                }
+                catch {
+                    return;
+                }
+                for (let t = 0; t < stopTimeoutMs && alive(); t += 100)
+                    await new Promise((r) => setTimeout(r, 100));
+                if (alive())
+                    process.kill(-pid, "SIGKILL");
+                return;
+            }
+            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
+                return;
+            const stopUnit = () => root([SYSTEMCTL, "stop", `${h.unit}.service`], { timeoutMs: stopTimeoutMs + 10_000 });
+            let r = await stopUnit();
+            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+                // A unit that outlives SIGKILL is wedged in its mount (a FUSE request its daemon never answers): kill the
+                // daemon so those requests fail and the processes can die, then stop once more.
+                await killDaemons(h.unit);
+                r = await stopUnit();
+                if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+                    throw new LocalHostError("STOP_FAILED", `systemctl stop ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+                }
+            }
+            await cleanMount(h.unit, String(h.mountpoint));
+            await root([SYSTEMCTL, "reset-failed", `${h.unit}.service`]);
+            await removeFile(tokenFile(h.unit));
+        },
+    };
+}
+/** Field 22 of /proc/<pid>/stat (start time in clock ticks), so a reused pid is never mistaken for the instance. */
+export function procStartTicks(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    let stat;
+    try {
+        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const rest = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    if (rest[0] === "Z" || rest[0] === "X")
+        return null;
+    return Number(rest[19]);
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./app.js";
+export * from "./claim.js";
+export { PathOutsideWorkError, type RefusalReason } from "./confine.js";
+export * from "./env.js";
+export * from "./errors.js";
+export * from "./fork.js";
+export * from "./hosts/daytona.js";
+export * from "./hosts/docker.js";
+export * from "./hosts/local-host.js";
+export * from "./local-run.js";
+export * from "./park.js";
+export * from "./run.js";
+export * from "./serve.js";
+export * from "./status.js";
+export * from "./store.js";
+export * from "./supervise.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+// Public API.
+export * from "./app.js";
+export * from "./claim.js";
+export { PathOutsideWorkError } from "./confine.js";
+export * from "./env.js";
+export * from "./errors.js";
+export * from "./fork.js";
+export * from "./hosts/daytona.js";
+export * from "./hosts/docker.js";
+export * from "./hosts/local-host.js";
+export * from "./local-run.js";
+export * from "./park.js";
+export * from "./run.js";
+export * from "./serve.js";
+export * from "./status.js";
+export * from "./store.js";
+export * from "./supervise.js";

package/dist/lease.d.ts

@@ -0,0 +1,7 @@
+export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
+export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunErrorCode, RunLease, StoreHeadSource } from "./run.js";
+export * from "./errors.js";
+export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
+export type { ArchilStore, OpenOptions, PragmaMismatch, Profile } from "./store.js";
+export type { AcquireOptions, ArchilHost, Claim, RunRef, Unmounted } from "./claim.js";
+export type { ClaimDir, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";

package/dist/lease.js

@@ -0,0 +1,6 @@
+// The narrow entry (`@parcha/pi-durable-disk/lease`) for a host that owns its own pi-durable Harness and store connections: the
+// claim's lifecycle without the supervisor, the host drivers, the CLI or the app contract. Importing it must not pull those
+// in (test/lease-entry.test.ts bundles it and checks); a name added here is part of that promise.
+export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
+export * from "./errors.js";
+export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";

package/dist/local-run.d.ts

@@ -0,0 +1,10 @@
+import type { AcquireOptions, Claim } from "./claim.js";
+import { type ClaimDir } from "./status.js";
+export interface LocalRun {
+    /** Takes the claim: the directory, made when it is missing. */
+    readonly acquire: (options: AcquireOptions) => Promise<Claim>;
+    /** Holds the directory open as the run's root; a local directory is not an Archil mount, so its type is not checked. */
+    readonly claimDir: (root: string) => Promise<ClaimDir>;
+}
+/** `openDurableRun`'s `acquire` and `claimDir` for a run in `root`, a directory on this machine. */
+export declare function localRun(root: string): LocalRun;

package/dist/local-run.js

@@ -0,0 +1,63 @@
+// A run on a plain local directory, for one machine: the claim is the directory itself. Nothing mounts and nothing is
+// delegated, so nothing but this machine's owner lock stands between two processes and the run: it is for a laptop, a CI
+// job or a test, never for a directory another machine can reach.
+//
+//   const run = await openDurableRun(ref, { ...localRun("/var/runs/run-1"), harness: { models, registry } });
+//
+// No mount token is needed (`acquire` is replaced). The claim's barrier does not sync the files the agent wrote: the
+// store's own commits are made durable by SQLite, and work/ is the operating system's to flush; a power loss can lose what
+// it had not written yet. It refuses once the claim is fenced, as a mount's does.
+//
+// Linux only, for now: the run's root is held open through /proc/self/fd (openClaimDir), and the default environment
+// (`archilEnv`) confines commands with `setpriv` (util-linux) and the file tools through /proc/self/fd. macOS has neither.
+import { mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { FencedError } from "./errors.js";
+import { openClaimDir } from "./status.js";
+/** `openDurableRun`'s `acquire` and `claimDir` for a run in `root`, a directory on this machine. */
+export function localRun(root) {
+    const dir = resolve(root);
+    return {
+        acquire: async ({ ref }) => {
+            await mkdir(dir, { recursive: true });
+            return new LocalClaim(ref, dir);
+        },
+        claimDir: (at) => openClaimDir(at, { fstype: null }),
+    };
+}
+class LocalClaim {
+    ref;
+    disk;
+    root;
+    work;
+    store;
+    /** `<root>/commands`: a local run has no unit cgroup, so the next open ends the commands a killed one left running. */
+    commands;
+    reused = false;
+    stray = null;
+    forced = false;
+    timings = { mountMs: 0, verifyMs: 0 };
+    #fence;
+    constructor(ref, root) {
+        this.ref = ref;
+        this.disk = ref.disk;
+        this.root = root;
+        this.work = join(root, "work");
+        this.store = join(root, "store");
+        this.commands = join(root, "commands");
+    }
+    get fenced() {
+        return this.#fence !== undefined;
+    }
+    markFenced(cause) {
+        this.#fence ??= { cause };
+    }
+    async barrier() {
+        if (this.#fence)
+            throw new FencedError(`${this.root} is fenced; nothing is retried on it`, { cause: this.#fence.cause });
+        return { ms: 0 };
+    }
+    async release() {
+        return { via: "none" };
+    }
+}

package/dist/park.d.ts

@@ -0,0 +1,92 @@
+import type { Context, JsonValue } from "@earendil-works/chord";
+import type { Harness, HarnessInspection } from "@earendil-works/pi-durable";
+import type { DurableRun, RunLease } from "./run.js";
+/**
+ * What parking and drain need of a run: its Harness, and the lease's status write and release. A `DurableRun` is one;
+ * a host that owns its Harness over `openRunLease` gets one from `leaseParkTarget`.
+ */
+export type ParkTarget = Pick<DurableRun, "harness" | "fenced" | "setStatus" | "release">;
+/**
+ * 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 declare function leaseParkTarget(lease: RunLease, harness: Harness, context?: Context): ParkTarget;
+/** localHost's threshold, far above twice its start (about 1.5 s); Cloudflare and Rivet park pi after 60 s too. */
+export declare const LOCAL_PARK_THRESHOLD_MS = 60000;
+export type BusyState = {
+    readonly kind: "busy";
+} | {
+    readonly kind: "idle";
+}
+/** Every task that could run sleeps until at least `until` (epoch ms, pi's clock), further away than the threshold. */
+ | {
+    readonly kind: "waiting";
+    readonly until: number;
+};
+/**
+ * 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 declare function waitDeadline(checkpoint: JsonValue | undefined): number | 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 declare function busyState(inspection: HarnessInspection, now: number, thresholdMs: number): BusyState;
+/** The default wake: run.json `sleeping` with `wakeAt` (null: idle, started on demand), written durably. */
+export declare function recordWake(run: Pick<ParkTarget, "setStatus">, at: number | null): Promise<void>;
+export interface ParkOptions {
+    /** A wait no longer than this keeps the instance up: per driver, at least twice the time the driver takes to start one. */
+    readonly thresholdMs: number;
+    /** Park a run with no live work once it stayed so this long; default never (only a request can wake an idle run). */
+    readonly idleMs?: number;
+    /**
+     * Record the wake before the release; default `recordWake`. A rejection that is not a fence keeps the instance up
+     * and pi's own timer ends the wait. A failed run.json write is a fence, as every error writing the claim's own files
+     * is: the instance exits 75 and the supervisor resumes the run after the lease.
+     */
+    readonly wake?: (run: ParkTarget, at: number | null) => Promise<void>;
+    /** Something outside pi needs the instance (an open request): it never parks while this returns true. */
+    readonly keepAwake?: () => boolean;
+    /** Stop admitting new work before the last check; returns the undo for a park that is called off. */
+    readonly quiesce?: () => () => void;
+    /** pi's clock (HarnessOptions.now); default Date.now. */
+    readonly now?: () => number;
+    readonly log?: (event: string, detail: Record<string, JsonValue>) => void;
+}
+export type ParkResult = {
+    readonly wakeAt: number | null;
+    readonly blocked: number;
+};
+export interface Parking {
+    /** Settles once the run parked and was released; stays pending while the instance stays up. */
+    readonly parked: Promise<ParkResult>;
+    /** Look again now (call it when `keepAwake` turns false). */
+    check(): void;
+    /** No new attempt; resolves with the park that was already under way, if any finished. */
+    stop(): Promise<ParkResult | undefined>;
+}
+/**
+ * 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 declare function watchParking(run: ParkTarget, options: ParkOptions): Parking;
+export interface DrainOptions {
+    /** Epoch ms after which the drain gives up and the run is released with its work interrupted. */
+    readonly deadline: number;
+    readonly now?: () => number;
+}
+/**
+ * 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 declare function drain(run: Pick<ParkTarget, "harness">, options: DrainOptions): Promise<BusyState>;