@parcha/pi-durable-disk 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/claim.d.ts

@@ -143,7 +143,7 @@ export declare function parseTokenNickname(nickname: string, prefix?: string): {
  * 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: {
+export declare function mintMountToken(control: Pick<ControlApi, "addUser">, opts: {
     nickname?: string;
     run?: {
         id: string;
@@ -158,7 +158,7 @@ export declare function mintMountToken(control: ControlApi, opts: {
     identifier: string;
     nickname: string;
 }>;
-export declare function removeMountToken(control: ControlApi, identifier: string): Promise<void>;
+export declare function removeMountToken(control: Pick<ControlApi, "removeUser">, 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
@@ -205,6 +205,12 @@ export declare function revoke(control: ControlApi, id: string): Promise<Delegat
 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>;
+/** A path of a disk, as one exclusive mount names it: `runs/<id>` for a run, any safe path for `withClaim`. */
+export type MountTarget = {
+    readonly disk: string;
+    readonly region: string;
+    readonly path: string;
+};
 /**
  * The errno codes of a stat on a FUSE mount whose daemon is gone: ENOTCONN once its connection is torn down, ECONNABORTED
  * for a stat already in flight while it is torn down. Codes, never messages: a message is translated by the locale.
@@ -216,6 +222,18 @@ export declare const DEAD_CONNECTION: ReadonlySet<string>;
  * in and moved aside. Any other live mount that refuses is never forced.
  */
 export declare function unmountClaim(mountpoint: string, host?: ArchilHost): Promise<Unmounted>;
+/** The most entries of a bare mountpoint the stray check looks at; past it, nothing is moved aside. */
+export declare const STRAY_CHECK_LIMIT = 100000;
+/**
+ * The entries under `dir` written since `since` (ms since the epoch), as paths relative to it, walked without following
+ * links. `unchecked` says why the walk could not look at every entry: more than `limit` of them, or one it could not
+ * read (an entry gone meanwhile is not one). A directory keeps its time when a file in it is rewritten in place, so only
+ * a walk that looked at every entry shows there is none.
+ */
+export declare function writtenSince(dir: string, since: number, limit?: number): Promise<{
+    fresh: string[];
+    unchecked: string | null;
+}>;
 /**
  * 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
@@ -224,4 +242,29 @@ export declare function unmountClaim(mountpoint: string, host?: ArchilHost): Pro
  * 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.
  */
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export declare const NO_TOKEN = "none";
 export declare function acquire(opts: AcquireOptions): Promise<Claim>;
+/** One exclusive mount of a path, as `withClaim` holds it: its own mountpoint, never reused. */
+export interface ExclusiveMount {
+    readonly root: string;
+    /** `archil sync`; a refusal (the mount was revoked) is a FencedError. */
+    barrier(): Promise<{
+        ms: number;
+    }>;
+    /** `archil unmount` (a dead mount is cleaned), and the mountpoint removed. */
+    unmount(): Promise<Unmounted>;
+}
+/**
+ * Mount `<disk>:/<path>` exclusively at `mountpoint`, a fresh directory of the caller's own, and verify it, with `probe` as
+ * the claim probe's content. Another client's delegation is HeldError CLAIM_HELD (`held` is added to its message); the
+ * rest fails as `acquire` does. Unlike `acquire`, a mount already there is never reused, and nothing is forced.
+ */
+export declare function exclusiveMount(target: MountTarget, mountpoint: string, token: string, options: {
+    readonly host?: ArchilHost;
+    readonly probe: string;
+    readonly held?: string;
+}): Promise<ExclusiveMount>;

package/dist/claim.js

@@ -3,7 +3,7 @@
 // a mount token and uses the archil client: mount, verify, barrier, release, dead-mount cleanup.
 import { spawn } from "node:child_process";
 import { readdirSync, readFileSync } from "node:fs";
-import { mkdir, open, readdir, readFile, rmdir, stat } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, readFile, rmdir, stat } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
@@ -364,9 +364,10 @@ async function mountEntry(host, mountpoint) {
     }
     return found;
 }
-function isOurs(entry, ref) {
-    const base = `${ref.disk}:/${runPath(ref.id)}`;
-    return entry.fstype === "fuse.archil" && (entry.source === base || entry.source === `${base}[${ref.region}]`);
+const targetOf = (ref) => ({ disk: ref.disk, region: ref.region, path: runPath(ref.id) });
+function isOurs(entry, target) {
+    const base = `${target.disk}:/${target.path}`;
+    return entry.fstype === "fuse.archil" && (entry.source === base || entry.source === `${base}[${target.region}]`);
 }
 /**
  * The errno codes of a stat on a FUSE mount whose daemon is gone: ENOTCONN once its connection is torn down, ECONNABORTED
@@ -412,10 +413,13 @@ async function moveAside(host, mountpoint, code) {
     if (!ok(r))
         throw new ClaimError(code, `${mountpoint} was moved aside but its daemon was not stopped (${detail(r)})`);
 }
+/** The archil client's own directory on the disk, where it keeps its bookkeeping (`client-<n>`, `unlinked`). */
+const ARCHIL_BOOKKEEPING = ".archil";
 /**
  * Release a live mount the kernel will not unmount (Sysbox): `archil checkin` gives the delegation back, the client must
- * then list none on the run, and only then is the mount moved aside and its daemon killed. Any failed step leaves the
- * mount where it is, as UNMOUNT_FAILED: a mount that may still hold the delegation is never abandoned.
+ * then list none on the run (its own bookkeeping under `.archil/` is not the run's), and only then is the mount moved
+ * aside and its daemon killed. Any failed step leaves the mount where it is, as UNMOUNT_FAILED: a mount that may still
+ * hold the delegation is never abandoned.
  */
 async function checkinAndMoveAside(host, mountpoint) {
     const c = await archil(host, ["checkin", mountpoint], host.timeoutMs.unmount);
@@ -429,7 +433,11 @@ async function checkinAndMoveAside(host, mountpoint) {
     catch {
         list = null;
     }
-    const mine = (p) => p === mountpoint || (typeof p === "string" && p.startsWith(`${mountpoint}/`));
+    // The client also lists its own bookkeeping on the disk, `<mp>/.archil/client-<n>` and its `unlinked` (made when a
+    // file under the mount is deleted), which a checkin of the run leaves and none can clear once the mount is read-only.
+    // It is outside the run's tree, so it never holds the run: every other delegation under the mount does.
+    const bookkeeping = (p) => p === `${mountpoint}/${ARCHIL_BOOKKEEPING}` || p.startsWith(`${mountpoint}/${ARCHIL_BOOKKEEPING}/`);
+    const mine = (p) => p === mountpoint || (typeof p === "string" && p.startsWith(`${mountpoint}/`) && !bookkeeping(p));
     const held = !Array.isArray(list) || list.some((x) => x?.state === "Active" && mine(x.path));
     if (held)
         throw new ClaimError("UNMOUNT_FAILED", `${mountpoint} still lists a delegation after archil checkin: ${(ok(d) ? d.stdout : detail(d)).trim().slice(0, 300)}`);
@@ -480,20 +488,23 @@ async function ensureMountpoint(host, dir) {
  * goes to the wrapper as one line on stdin (`bin/archil-scoped`), with or without sudo.
  */
 async function mountRun(host, ref, mountpoint, token, force) {
-    const path = runPath(ref.id);
-    const args = [host.archil, "mount", ...(force ? ["--force"] : []), `${ref.disk}:/${path}`, mountpoint, "--region", ref.region];
+    await mountTarget(host, targetOf(ref), mountpoint, token, force);
+}
+async function mountTarget(host, target, mountpoint, token, force, held = "") {
+    const { path } = target;
+    const args = [host.archil, "mount", ...(force ? ["--force"] : []), `${target.disk}:/${path}`, mountpoint, "--region", target.region];
     const r = await sh(asRoot(host, args), host.timeoutMs.mount, `${token}\n`);
     const entry = await mountEntry(host, mountpoint);
-    if (ok(r) && entry && isOurs(entry, ref))
+    if (ok(r) && entry && isOurs(entry, target))
         return;
     if (entry)
         await unmountWith(host, mountpoint).catch(() => { });
     if (ok(r))
-        throw new ClaimError("MOUNT_FAILED", `archil mount ${path} exited 0 but ${mountpoint} is not an archil mount of the run`);
+        throw new ClaimError("MOUNT_FAILED", `archil mount ${path} exited 0 but ${mountpoint} is not an archil mount of ${path}`);
     if (STALE_MARKER.test(r.stderr))
         throw new ClaimError("MOUNT_FAILED", `an archil daemon of this host still runs for ${mountpoint}: ${detail(r, token)}`);
     if (!force && r.stderr.includes(HELD_MARKER))
-        throw new HeldError("claim", `${path} is held by another client (${detail(r, token)})`);
+        throw new HeldError("claim", `${path} is held by another client${held} (${detail(r, token)})`);
     if (r.stderr.includes(NOT_EMPTY_MARKER) || (MISLEADING_REFUSAL.test(r.stderr) && (await entries(mountpoint)) > 0)) {
         throw new ClaimError("MOUNTPOINT_NOT_EMPTY", `archil mount ${path} refused ${mountpoint}, which is not empty: ${detail(r, token)}`);
     }
@@ -558,6 +569,58 @@ async function clearStaleDaemon(host, ref, mountpoint) {
     process.stderr.write(`${JSON.stringify({ at: new Date().toISOString(), event: "stale archil daemon killed", run: ref.id, pids })}\n`);
     return pids;
 }
+/** The most entries of a bare mountpoint the stray check looks at; past it, nothing is moved aside. */
+export const STRAY_CHECK_LIMIT = 100_000;
+/**
+ * The entries under `dir` written since `since` (ms since the epoch), as paths relative to it, walked without following
+ * links. `unchecked` says why the walk could not look at every entry: more than `limit` of them, or one it could not
+ * read (an entry gone meanwhile is not one). A directory keeps its time when a file in it is rewritten in place, so only
+ * a walk that looked at every entry shows there is none.
+ */
+export async function writtenSince(dir, since, limit = STRAY_CHECK_LIMIT) {
+    const fresh = [];
+    const dirs = [""];
+    let seen = 0;
+    const failed = (error) => {
+        const code = error.code;
+        return code === "ENOENT" ? null : `an entry it cannot read (${code ?? "an unknown error"})`;
+    };
+    for (let i = 0; i < dirs.length; i++) {
+        const rel = dirs[i];
+        let names;
+        try {
+            names = await readdir(join(dir, rel));
+        }
+        catch (error) {
+            const unchecked = failed(error);
+            if (unchecked)
+                return { fresh, unchecked };
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (++seen > limit)
+                return { fresh, unchecked: `more than ${limit} entries` };
+            const path = rel ? `${rel}/${name}` : name;
+            let st;
+            try {
+                st = await lstat(join(dir, path));
+            }
+            catch (error) {
+                const unchecked = failed(error);
+                if (unchecked)
+                    return { fresh, unchecked };
+                continue;
+            }
+            if (st.mtimeMs >= since)
+                fresh.push(path);
+            if (st.isDirectory())
+                dirs.push(path);
+        }
+    }
+    return { fresh, unchecked: null };
+}
+/** The exit of a start refused for the app's own writes before its claim (EX_DATAERR): a restart would write them again. */
+const EXIT_WRITTEN_BEFORE_MOUNT = 65;
 /** How many entries a directory holds; 0 when it cannot be read. */
 const entries = (dir) => readdir(dir).then((names) => names.length, () => 0);
 /**
@@ -566,11 +629,28 @@ const entries = (dir) => readdir(dir).then((names) => names.length, () => 0);
  * directory with its owner and mode: archil refuses to mount over entries, and nothing in them may enter the run. One
  * line on stderr names the run and the count of entries, never a name or a byte of them. An unreadable mountpoint goes
  * to the wrapper too, which looks as root.
+ *
+ * Entries written since this process started are not an earlier incarnation's leftovers but this one's own writes
+ * before its claim mounted (an app's factory writing under ctx.root, which runs before the mount): moving them aside
+ * would lose them silently and the run would later find them gone (ENOENT). The start is refused instead,
+ * MOUNTPOINT_WRITTEN (exit 65, terminal: a restart writes them again), naming the first of them. A mountpoint whose
+ * entries the check cannot all look at (more than STRAY_CHECK_LIMIT, or one this process cannot read) may hide such a
+ * write, so it is refused too, MOUNTPOINT_UNCHECKED (exit 65: someone looks at it), naming none of them.
  */
 async function moveStrayAside(host, ref, mountRoot, mountpoint) {
     const names = await readdir(mountpoint).catch(() => null);
     if (names && names.length === 0)
         return null;
+    if (names) {
+        const { fresh, unchecked } = await writtenSince(mountpoint, performance.timeOrigin);
+        if (fresh.length > 0) {
+            const named = fresh.slice(0, 4).map((p) => `<mp>/${p}`).join(", ");
+            throw new ClaimError("MOUNTPOINT_WRITTEN", `the bare mountpoint <mp> of ${runPath(ref.id)} holds ${fresh.length} entr${fresh.length === 1 ? "y" : "ies"} written since this incarnation started, before its claim mounted: ${named}`.slice(0, 240), { exitCode: EXIT_WRITTEN_BEFORE_MOUNT });
+        }
+        if (unchecked) {
+            throw new ClaimError("MOUNTPOINT_UNCHECKED", `the bare mountpoint <mp> of ${runPath(ref.id)} holds ${unchecked}, so this incarnation cannot rule out its own writes before its claim mounted: nothing is moved aside. Look at it, then move it aside by hand`, { exitCode: EXIT_WRITTEN_BEFORE_MOUNT });
+        }
+    }
     const tag = Date.now().toString(36);
     const r = await archil(host, ["stray", mountpoint, tag]);
     if (!ok(r))
@@ -596,7 +676,10 @@ async function moveStrayAside(host, ref, mountRoot, mountpoint) {
  * the run but not that this mount does.
  */
 async function verify(host, ref, mountpoint) {
-    const path = runPath(ref.id);
+    await verifyTarget(host, runPath(ref.id), mountpoint, `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
+}
+/** `verify` for any path; `probe` is what the claim probe holds. */
+async function verifyTarget(host, path, mountpoint, probe) {
     const r = await archil(host, ["delegations", "--json", mountpoint]);
     if (!ok(r))
         throw new ClaimError("CLAIM_NOT_VERIFIED", `archil delegations ${mountpoint}: ${detail(r)}`);
@@ -612,7 +695,7 @@ async function verify(host, ref, mountpoint) {
     if (!active)
         throw new ClaimError("CLAIM_NOT_VERIFIED", `${mountpoint} holds no Active delegation on ${path}: ${r.stdout.trim().slice(0, 300)}`);
     try {
-        await host.persist(join(mountpoint, CLAIM_PROBE), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
+        await host.persist(join(mountpoint, CLAIM_PROBE), probe);
     }
     catch (err) {
         throw ownWriteFenced(join(mountpoint, CLAIM_PROBE), err);
@@ -626,6 +709,11 @@ async function verify(host, ref, mountpoint) {
  * 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.
  */
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export const NO_TOKEN = "none";
 export async function acquire(opts) {
     const { ref, token } = opts;
     const path = runPath(ref.id);
@@ -641,7 +729,7 @@ export async function acquire(opts) {
     let reused = false;
     const existing = await mountEntry(host, root);
     if (existing) {
-        if (!isOurs(existing, ref))
+        if (!isOurs(existing, targetOf(ref)))
             throw new ClaimError("MOUNTPOINT_BUSY", `${root} already holds ${existing.fstype} ${existing.source}`);
         if (await isDead(host, root))
             await cleanDead(host, root);
@@ -649,6 +737,11 @@ export async function acquire(opts) {
             reused = true;
     }
     let stray = null;
+    // No live mount to reuse and no token to mount with: a restart whose mount went with the failed incarnation. It cannot
+    // hold the run again, so it is fenced (75, terminal) at once, and the next start of the run brings a new token.
+    if (!reused && token === NO_TOKEN) {
+        throw new FencedError(`no live mount of ${path} to reuse at ${root}, and this incarnation was given no mount token: it cannot mount the run again; a new start brings a new token`, { code: "CLAIM_GONE_NO_TOKEN" });
+    }
     if (!reused) {
         await ensureMountpoint(host, root);
         await clearStaleDaemon(host, ref, root);
@@ -730,3 +823,40 @@ class ArchilClaim {
         return { via };
     }
 }
+/**
+ * Mount `<disk>:/<path>` exclusively at `mountpoint`, a fresh directory of the caller's own, and verify it, with `probe` as
+ * the claim probe's content. Another client's delegation is HeldError CLAIM_HELD (`held` is added to its message); the
+ * rest fails as `acquire` does. Unlike `acquire`, a mount already there is never reused, and nothing is forced.
+ */
+export async function exclusiveMount(target, mountpoint, token, options) {
+    if (!token || /[\r\n]/.test(token))
+        throw new ClaimError("INVALID_ARGUMENT", "no mount token, or one with a line break");
+    const host = resolveHost(options.host);
+    if (await mountEntry(host, mountpoint))
+        throw new ClaimError("MOUNTPOINT_BUSY", `${mountpoint} is already a mount`);
+    await ensureMountpoint(host, mountpoint);
+    try {
+        await mountTarget(host, target, mountpoint, token, false, options.held);
+    }
+    catch (err) {
+        await rmdir(mountpoint).catch(() => { });
+        throw err;
+    }
+    try {
+        await verifyTarget(host, target.path, mountpoint, options.probe);
+    }
+    catch (err) {
+        await unmountWith(host, mountpoint).catch(() => { });
+        throw err;
+    }
+    return {
+        root: mountpoint,
+        async barrier() {
+            const r = await archil(host, ["sync", mountpoint], host.timeoutMs.sync);
+            if (ok(r))
+                return { ms: r.ms };
+            throw new FencedError(`archil sync ${mountpoint}: ${detail(r)}`);
+        },
+        unmount: () => unmountWith(host, mountpoint),
+    };
+}

package/dist/cli.js

@@ -12,7 +12,7 @@ import { closeSync, openSync, readFileSync, realpathSync, statSync } from "node:
 import { basename, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-import { ARCHIL_SCOPED, DEFAULT_MOUNT_ROOT, runPath, TOKEN_PREFIX, unmountClaim } from "./claim.js";
+import { ARCHIL_SCOPED, DEFAULT_MOUNT_ROOT, NO_TOKEN, runPath, TOKEN_PREFIX, unmountClaim } from "./claim.js";
 import { archilEnv } from "./env.js";
 import { exitCodeFor, FencedError, PdaError } from "./errors.js";
 import { fork } from "./fork.js";
@@ -165,7 +165,7 @@ export async function cliControl(values, client) {
  */
 async function readToken(values) {
     if (!values["token-stdin"])
-        return "none";
+        return NO_TOKEN;
     let text = "";
     for await (const chunk of process.stdin)
         text += chunk;
@@ -176,12 +176,13 @@ async function readToken(values) {
     catch {
         // already closed
     }
-    return text.trim() || "none";
+    return text.trim() || NO_TOKEN;
 }
 /**
  * The instance a host driver starts: openDurableRun with the app module's Harness options (src/app.ts), the
  * driver's handle as run.json's holder, the mount token from stdin (read once, then stdin is closed), and the lease
- * periods. The app loads before anything mounts; a missing or throwing module, or a failed `onOpen`, is AppError (exit 1,
+ * periods. The app's factory runs once the claim is held (`afterClaim`: the run's directory is mounted, so `ctx.root` is
+ * the live directory) and the Harness opens with what it returns; a missing or throwing module, or a failed `onOpen`, is AppError (exit 1,
  * so the unit retries within systemd's start limit; a restart in place reuses the claim). A fence of any kind kills the
  * run's commands and exits 75 inside openDurableRun.
  *
@@ -220,15 +221,10 @@ async function runInstance(values) {
     const mountRoot = str(values["mount-root"], DEFAULT_MOUNT_ROOT);
     const root = dir ?? join(mountRoot, runPath(ref.id));
     const log = (event, extra = {}) => process.stderr.write(`${JSON.stringify({ at: new Date().toISOString(), event, run: ref.id, ...extra })}\n`);
+    // The app's factory runs once the claim is held (`afterClaim`), so `ctx.root` is the live directory whenever app code
+    // runs; what it returns opens the Harness. Serve starts before the open, with the root options the factory fills in.
     let app;
-    try {
-        app = await loadApp(str(values.app), { ref, root, work: join(root, "work"), store: join(root, "store") });
-    }
-    catch (err) {
-        log("app failed", { code: err.code, message: err.message });
-        return exitCodeFor(err);
-    }
-    const { onOpen, beforeResume, root: rootOptions, wake: appWake, ...harness } = app;
+    const rootOptions = {};
     const holder = JSON.parse(process.env.PDA_HOLDER ?? "{}");
     // On a local directory nothing else knows this instance: its start ticks go into the holder, so `status --dir` tells it
     // from a later process that reuses its pid (a driver's handle already carries them).
@@ -252,7 +248,12 @@ async function runInstance(values) {
         run = await openDurableRun(ref, {
             // A local directory is its own claim (no mount, no token); a disk's run is mounted with a token.
             ...(dir === undefined ? { mountToken: await readToken(values), mountRoot, host: { archil: str(values.archil) } } : localRun(dir)),
-            harness,
+            afterClaim: async (claim) => {
+                app = await loadApp(str(values.app), { ref, root: claim.root, work: claim.work, store: claim.store });
+                const { onOpen: _onOpen, beforeResume, root: appRoot, wake: _wake, ...harness } = app;
+                Object.assign(rootOptions, appRoot ?? {});
+                return { harness, ...(beforeResume ? { beforeResume } : {}) };
+            },
             ...(runAs
                 ? { env: (c) => archilEnv(c, { runAs: { uid: runAs.uid, gid: runAs.gid }, shellEnv: { HOME: runAs.home, USER: runAs.name, LOGNAME: runAs.name } }) }
                 : {}),
@@ -260,16 +261,16 @@ async function runInstance(values) {
             ownCgroup: cgroup.owns,
             lease: Object.fromEntries(Object.entries(lease).filter(([, v]) => v !== undefined)),
             onStep: (step, t) => void (steps[step] = Math.round(t)),
-            ...(beforeResume ? { beforeResume } : {}),
         });
     }
     catch (err) {
-        log("open failed", { code: err.code, exitCode: exitCodeFor(err), message: err.message, steps });
+        log(err instanceof AppError ? "app failed" : "open failed", { code: err.code, exitCode: exitCodeFor(err), message: err.message, steps });
         await server?.close();
         return exitCodeFor(err);
     }
     server?.attach(run);
     log("running", { generation: run.generation, steps, ...(server ? { serve: server.url } : {}) });
+    const { onOpen, wake: appWake } = app;
     return serveUntilDone(run, onOpen, onSigterm, log, process, {
         drainMs,
         ...(server ? { server } : {}),

package/dist/errors.d.ts

@@ -30,11 +30,12 @@ export declare class HeldError extends PdaError {
         code?: string;
     });
 }
-export type ClaimErrorCode = "INVALID_ARGUMENT" | "MOUNTPOINT_BUSY" | "MOUNTPOINT_NOT_EMPTY" | "MOUNT_FAILED" | "CLAIM_NOT_VERIFIED" | "ARCHIL_CLI_FAILED" | "UNMOUNT_FAILED" | "DEAD_MOUNT_CLEANUP_FAILED" | "CLAIM_RELEASED" | "CONTROL_API_FAILED";
+export type ClaimErrorCode = "INVALID_ARGUMENT" | "MOUNTPOINT_BUSY" | "MOUNTPOINT_NOT_EMPTY" | "MOUNTPOINT_WRITTEN" | "MOUNTPOINT_UNCHECKED" | "MOUNT_FAILED" | "CLAIM_NOT_VERIFIED" | "ARCHIL_CLI_FAILED" | "UNMOUNT_FAILED" | "DEAD_MOUNT_CLEANUP_FAILED" | "CLAIM_RELEASED" | "CONTROL_API_FAILED" | "NOT_RELEASED";
 /** Any other claim failure (bad input, a refused or unverifiable mount, a CLI or control API failure). Exit 1. */
 export declare class ClaimError extends PdaError {
     constructor(code: ClaimErrorCode, message: string, options?: {
         cause?: unknown;
+        exitCode?: number;
     });
 }
 export declare function exitCodeFor(err: unknown): number;

package/dist/hosts/attempt-env.d.ts

@@ -0,0 +1,3 @@
+import type { StartAttempt } from "../supervise.js";
+/** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
+export declare function attemptEnv(attempt: StartAttempt | undefined, refuse: (message: string) => Error): Record<string, string>;

package/dist/hosts/attempt-env.js

@@ -0,0 +1,15 @@
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DRIVER_KEYS = new Set(["PATH", "PDA_HOLDER"]);
+/** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
+export function attemptEnv(attempt, refuse) {
+    const env = attempt?.env ?? {};
+    for (const [name, value] of Object.entries(env)) {
+        if (!ENV_NAME.test(name))
+            throw refuse(`${JSON.stringify(name)} is not an environment variable name`);
+        if (DRIVER_KEYS.has(name))
+            throw refuse(`${name} is the driver's: a start cannot set it`);
+        if (typeof value !== "string" || value.includes("\0"))
+            throw refuse(`the value of ${name} is not a string without NUL`);
+    }
+    return env;
+}

package/dist/hosts/daytona-launch.js

@@ -9,8 +9,10 @@
 //   status <name>  print running, stopped or failed from the state file and whether the processes still live
 //   stop <name>    SIGTERM the launcher (it drains the instance), SIGKILL both after the timeout, print the state
 // Files live in a root-only directory (default /run/pda, 0700), which the run user can never traverse: `<name>.json`
-// (the spec), `<name>.token` (gone once read), `<name>.state`, `<name>.log` (the instance's output). Only the first
-// incarnation gets the token; a restart in place reads an empty stdin and reuses its live mount, as under localHost.
+// (the spec), `<name>.token` (gone once read), `<name>.state`, `<name>.log` (the instance's output). Every incarnation of
+// the attempt gets its token on stdin: a restart whose mount is still live reuses it and never needs the token, and one
+// whose mount went with the failed incarnation mounts again (a takeover in between makes that mount HeldError, 76,
+// terminal). The token lives in this launcher's memory for the attempt.
 // No cgroup per incarnation: commands a crashed instance detached can outlive it until the box is deleted.
 import { spawn } from "node:child_process";
 import { closeSync, existsSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -128,9 +130,9 @@ export async function serve(dir, name) {
     try {
         for (;;) {
             const env = { PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: ids.home, ...spec.env };
-            const first = token !== null;
+            const piped = Boolean(token);
             try {
-                child = spawn(spec.argv[0], spec.argv.slice(1), { uid: ids.uid, gid: ids.gid, env, cwd: "/", stdio: [first ? "pipe" : "ignore", log, log], detached: true });
+                child = spawn(spec.argv[0], spec.argv.slice(1), { uid: ids.uid, gid: ids.gid, env, cwd: "/", stdio: [piped ? "pipe" : "ignore", log, log], detached: true });
                 await new Promise((resolve, reject) => {
                     child.once("spawn", resolve);
                     child.once("error", reject);
@@ -140,10 +142,9 @@ export async function serve(dir, name) {
                 save({ phase: "exited", instance: null, instanceTicks: null, exit: 1, reason: `spawn failed: ${err.message}` });
                 return state;
             }
-            if (first) {
+            if (piped) {
                 child.stdin.on("error", () => { });
-                child.stdin.end(token ? `${token}\n` : "");
-                token = null;
+                child.stdin.end(`${token}\n`);
             }
             save({ phase: stopping ? "stopping" : "running", instance: child.pid, instanceTicks: procStartTicks(child.pid), spawned: state.spawned + 1, exit: null, signal: null });
             if (stopping)

package/dist/hosts/daytona.d.ts

@@ -7,12 +7,37 @@ export type SandboxInfo = {
     id: string;
     name: string;
     state?: string;
+    /** The box's size as Daytona allocates it: vCPUs, GPUs, memory and disk (the API's GB). */
+    cpu?: number;
+    gpu?: number;
+    memory?: number;
+    disk?: number;
+    createdAt?: string;
     snapshot?: string;
     labels?: Record<string, string>;
     target?: string;
     toolboxProxyUrl?: string;
     errorReason?: string;
 };
+/**
+ * Daytona's published list prices, as its pricing page gave them on `readOn`: billed per second, quoted per hour, for
+ * each vCPU, each GiB of memory and each GiB of disk. The page's footnote "Price per GiB after first 5 free" is applied
+ * to storage (disk) only: its placement is ambiguous and could be read as covering memory too, so this is a choice.
+ * The page lists GPU rates per GPU model; this driver does not map a box's GPU to a model, so a GPU box is unpriced.
+ */
+export declare const DAYTONA_LIST_PRICES: {
+    readonly page: "https://www.daytona.io/pricing";
+    readonly readOn: "2026-10-16";
+    readonly vcpuPerHour: 0.0504;
+    readonly memoryGiBPerHour: 0.0162;
+    readonly diskGiBPerHour: 0.000108;
+    readonly freeDiskGiB: 5;
+};
+/**
+ * A box's list price per second at DAYTONA_LIST_PRICES, from its size; null when its size is unknown or it has a GPU
+ * (priced per GPU model on the page, which this driver does not map).
+ */
+export declare function daytonaUsdPerSecond(size: Pick<SandboxInfo, "cpu" | "gpu" | "memory" | "disk">): number | null;
 export type CreateSandboxBody = {
     name: string;
     snapshot: string;
@@ -60,7 +85,7 @@ export interface DaytonaRestOptions {
 }
 /** The REST API with an API key (Bearer). Error messages carry the method, path and status, never a header or a body sent. */
 export declare function daytonaRest(options: DaytonaRestOptions): DaytonaClient;
-export type DaytonaHostErrorCode = "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED" | "DAYTONA_API_FAILED";
+export type DaytonaHostErrorCode = "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED" | "KILL_FAILED" | "DAYTONA_API_FAILED";
 export declare class DaytonaHostError extends PdaError {
     constructor(code: DaytonaHostErrorCode, message: string, options?: {
         cause?: unknown;
@@ -133,7 +158,7 @@ export interface DaytonaHostOptions {
 export declare function sandboxStatus(state: string | undefined): HostStatus | "check";
 /** A Daytona-safe box name for a run: lowercase, at most 63 characters, unique per call. */
 export declare function sandboxName(prefix: string, runId: string, now: number): string;
-export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & {
+export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
     readonly fleet: string;
     readonly mountRoot: string;
 };