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

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

@@ -60,7 +60,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 +133,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;
 };

package/dist/hosts/daytona.js

@@ -15,6 +15,7 @@
 // in it, the commands a crashed incarnation detached included. The supervisor holds the API key; boxes never do.
 import { DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
 import { PdaError } from "../errors.js";
+import { attemptEnv } from "./attempt-env.js";
 import { LAUNCH_DIR } from "./daytona-launch.js";
 import { TERMINAL_EXITS } from "./local-host.js";
 export const DAYTONA_API_URL = "https://app.daytona.io/api";
@@ -258,10 +259,12 @@ export function daytonaHost(opts) {
     return {
         fleet,
         mountRoot,
-        async start(ref, mountToken) {
+        kills: "box",
+        async start(ref, mountToken, attempt) {
             runPath(ref.id);
             if (!mountToken)
                 throw new DaytonaHostError("INVALID_ARGUMENT", "no mount token");
+            const extra = attemptEnv(attempt, (m) => new DaytonaHostError("INVALID_ARGUMENT", m));
             const t0 = now();
             const name = sandboxName(prefix, ref.id, t0);
             const body = {
@@ -285,7 +288,7 @@ export function daytonaHost(opts) {
                 const handle = { driver: "daytona", fleet, target: box.target ?? opts.target ?? null, sandboxId: box.id, name, mountpoint: `${mountRoot}/${runPath(ref.id)}` };
                 const spec = {
                     argv: [...command, "run", "--disk", ref.disk, "--region", ref.region, "--id", ref.id, "--mount-root", mountRoot, "--archil", archil, ...(opts.runArgs ?? []), "--token-stdin"],
-                    env: { ...opts.env, PDA_HOLDER: JSON.stringify(handle) },
+                    env: { ...opts.env, ...extra, PDA_HOLDER: JSON.stringify(handle) },
                     user,
                     group,
                     restart: opts.restart !== false,
@@ -364,6 +367,34 @@ export function daytonaHost(opts) {
                 }
             }
         },
+        async kill(h) {
+            if (!mine(h))
+                return;
+            const id = h.sandboxId;
+            let box;
+            try {
+                box = await client.get(id);
+            }
+            catch (err) {
+                throw new DaytonaHostError("KILL_FAILED", `reading sandbox ${h.name} to confirm it is this fleet's: ${err.message}`, { cause: err });
+            }
+            if (box === null || box.labels?.[LABEL_FLEET] !== fleet)
+                return;
+            // The box goes with everything in it, the instance and its mount: no launcher stop, no drain.
+            try {
+                await client.remove(id);
+            }
+            catch (first) {
+                // A delete refused mid-transition: power the box off, then delete again.
+                await client.stop(id, true).catch(() => { });
+                try {
+                    await client.remove(id);
+                }
+                catch (err) {
+                    throw new DaytonaHostError("KILL_FAILED", `deleting sandbox ${h.name} failed: ${err.message}`, { cause: first });
+                }
+            }
+        },
     };
 }
 /** Delete every box of a fleet (the janitor after a crash of whoever started them); returns what it asked to delete. */

package/dist/hosts/docker.d.ts

@@ -58,7 +58,7 @@ export interface DockerHostOptions {
     exec?: DockerRunner;
 }
 export declare class DockerHostError extends PdaError {
-    constructor(code: "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED" | "DOCKER_FAILED", message: string, options?: {
+    constructor(code: "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED" | "KILL_FAILED" | "DOCKER_FAILED", message: string, options?: {
         cause?: unknown;
     });
 }
@@ -95,7 +95,7 @@ export type ContainerInfo = {
     startedAt: string | null;
     finishedAt: string | null;
 };
-export declare function dockerHost(opts?: DockerHostOptions): HostDriver & {
+export declare function dockerHost(opts?: DockerHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
     readonly fleet: string;
     readonly mountRoot: string;
     describe(handle: HostHandle): Promise<ContainerInfo | null>;

package/dist/hosts/docker.js

@@ -23,6 +23,7 @@ import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:p
 import { DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
 import { PdaError } from "../errors.js";
 import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
+import { attemptEnv } from "./attempt-env.js";
 export class DockerHostError extends PdaError {
     constructor(code, message, options = {}) {
         super(code, message, options);
@@ -191,8 +192,8 @@ export function dockerHost(opts = {}) {
         if (!ok(r) && !NO_SUCH.test(r.stderr))
             throw new DockerHostError("DOCKER_FAILED", `docker rm -f ${ref}: ${firstLine(r)}`);
     }
-    function createArgs(ref, name, attempt, holder, profile) {
-        const env = { ...opts.env, PDA_HOLDER: JSON.stringify(holder) };
+    function createArgs(ref, name, attempt, holder, profile, extra) {
+        const env = { ...opts.env, ...extra, PDA_HOLDER: JSON.stringify(holder) };
         const runFlags = [
             "run",
             "--disk", ref.disk,
@@ -228,10 +229,10 @@ export function dockerHost(opts = {}) {
             ...runFlags,
         ];
     }
-    async function create(ref, name, attempt, holder) {
+    async function create(ref, name, attempt, holder, extra) {
         const profile = await apparmor();
         for (let tries = 0;; tries++) {
-            const r = await run(createArgs(ref, name, attempt, holder, profile), { timeoutMs: 120_000 });
+            const r = await run(createArgs(ref, name, attempt, holder, profile, extra), { timeoutMs: 120_000 });
             if (ok(r))
                 return { id: r.stdout.trim().split("\n").at(-1).trim() };
             if (!IN_USE.test(r.stderr) || tries > 0)
@@ -270,6 +271,7 @@ export function dockerHost(opts = {}) {
     return {
         fleet,
         mountRoot,
+        kills: "box",
         async start(ref, token, attemptInfo) {
             runPath(ref.id);
             if (!opts.image)
@@ -277,11 +279,12 @@ export function dockerHost(opts = {}) {
             if (!token || /[\r\n]/.test(token))
                 throw new DockerHostError("INVALID_ARGUMENT", "no mount token, or one with a line break");
             const attempt = attemptInfo?.attempt ?? null;
+            const extra = attemptEnv(attemptInfo, (m) => new DockerHostError("INVALID_ARGUMENT", m));
             const name = `${prefix}${ref.id}-${diskKey(ref)}-${attempt === null ? `t${Date.now().toString(36)}` : `g${attempt}`}`;
             if (!NAME_SAFE.test(name))
                 throw new DockerHostError("INVALID_ARGUMENT", `container name ${name} is not safe`);
             const handle = { driver: "docker", fleet, daemon: await daemon(), name, mountpoint: posix.join(mountRoot, runPath(ref.id)), image: opts.image };
-            const made = await create(ref, name, attempt, handle);
+            const made = await create(ref, name, attempt, handle, extra);
             // An earlier start of this attempt made the container: the token given to this start was not used.
             if ("adopted" in made)
                 return { ...handle, adopted: true };
@@ -336,6 +339,20 @@ export function dockerHost(opts = {}) {
             if (await inspect(ref))
                 throw new DockerHostError("STOP_FAILED", `container ${ref} is still there after docker rm -f`);
         },
+        async kill(h) {
+            if (!(await mine(h)))
+                return;
+            const ref = target(h);
+            const found = await inspect(ref);
+            if (!found || found.labels["pda.fleet"] !== fleet)
+                return;
+            // SIGKILL, no stop timeout: the container dies with its mount (its own namespace), as on a power loss. It is left
+            // exited, not removed; the next start of the run removes it.
+            const r = await run(["kill", ref], { timeoutMs: 30_000 });
+            if (!ok(r) && !NO_SUCH.test(r.stderr) && (await inspect(ref).then((f) => f && containerStatus(f.state) === "running"))) {
+                throw new DockerHostError("KILL_FAILED", `docker kill ${ref}: ${firstLine(r)}`);
+            }
+        },
     };
 }
 /** The bind mount of the app's directory (read-only, its node_modules hidden) and the module's path inside the container. */

package/dist/hosts/local-host.d.ts

@@ -50,7 +50,7 @@ export interface LocalHostOptions {
     procMounts?: string;
 }
 export declare class LocalHostError extends PdaError {
-    constructor(code: "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED", message: string, options?: {
+    constructor(code: "INVALID_ARGUMENT" | "START_FAILED" | "STOP_FAILED" | "KILL_FAILED", message: string, options?: {
         cause?: unknown;
     });
 }
@@ -66,7 +66,7 @@ export declare function currentBootId(): string;
 export declare function parseShow(text: string): Record<string, string>;
 /** A unit's state as a host status: loaded and active (or restarting) is running; unloaded is gone. */
 export declare function unitStatus(show: Record<string, string>): HostStatus;
-export declare function localHost(opts?: LocalHostOptions): HostDriver & {
+export declare function localHost(opts?: LocalHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
     readonly hostName: string;
     readonly mountRoot: string;
 };