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

package/dist/hosts/daytona-launch.js

@@ -9,11 +9,13 @@
 //   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, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { procStartTicks, TERMINAL_EXITS } from "./local-host.js";
@@ -43,14 +45,17 @@ function writeState(path, state) {
 // Only a real process with its start ticks: `stop` signals these pids, the instance's as a group, and a pid of 1 or below
 // names a group (`kill(-1)` is every process this user may signal). The state file holds whatever was written there.
 const alive = (pid, ticks) => Number.isInteger(pid) && pid > 1 && typeof ticks === "number" && procStartTicks(pid) === ticks;
-/** running while either process lives; otherwise stopped after a clean exit, failed after any other end. */
+/** running while either process lives and the launcher has not recorded its exit; otherwise stopped after a clean exit,
+ * failed after any other end. Every "exited" the launcher saves is final and comes after its instance ended, so once it is
+ * saved (and no instance lives) the record is the answer, even while the launcher's own process is still exiting. */
 export function launchStatus(dir, name) {
     const state = readState(dir, name);
     if (!state)
         return { status: "failed", state: null, launcherAlive: false, instanceAlive: false };
     const launcherAlive = alive(state.launcher, state.launcherTicks);
     const instanceAlive = alive(state.instance, state.instanceTicks);
-    if (launcherAlive || instanceAlive)
+    const ended = state.phase === "exited" && !instanceAlive;
+    if (!ended && (launcherAlive || instanceAlive))
         return { status: "running", state, launcherAlive, instanceAlive };
     const clean = state.phase === "exited" && state.exit === 0;
     return { status: clean ? "stopped" : "failed", state, launcherAlive, instanceAlive };
@@ -125,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);
@@ -137,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)
@@ -216,8 +220,12 @@ export async function stop(dir, name, timeoutMs) {
         }
     };
     let s = launchStatus(dir, name);
-    if (s.status !== "running")
+    if (s.status !== "running") {
+        // The launcher recorded its exit and is ending on its own; a launcher process that outstays its record is still sent away.
+        if (s.launcherAlive)
+            kill(s.state.launcher, s.state.launcherTicks, "SIGTERM");
         return s;
+    }
     if (s.launcherAlive)
         kill(s.state.launcher, s.state.launcherTicks, "SIGTERM");
     else
@@ -262,7 +270,22 @@ async function main(argv) {
             return 2;
     }
 }
-if (process.argv[1] && resolve(process.argv[1]) === LAUNCH_SCRIPT) {
+/**
+ * Whether Node was started with this module. LAUNCH_SCRIPT comes from import.meta.url, which is the real path; argv[1] is
+ * the path as given, which may go through a link (a symlinked package directory, pnpm's linked node_modules).
+ */
+function invokedAsMain() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return realpathSync(arg) === LAUNCH_SCRIPT;
+    }
+    catch {
+        return resolve(arg) === LAUNCH_SCRIPT;
+    }
+}
+if (invokedAsMain()) {
     main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
         process.stderr.write(`${err.message}\n`);
         process.exit(1);

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";
@@ -121,7 +122,11 @@ export class DaytonaHostError extends PdaError {
         super(code, message, options);
     }
 }
-const BOX_PATH = /^\/[A-Za-z0-9._/-]+$/;
+// Shell-inert characters only: the paths go into launcher command lines. `@` admits npm's scoped package directories
+// (`node_modules/@scope/pkg`), where the package is installed with npm and not copied to a fixed directory.
+const BOX_PATH = /^\/[A-Za-z0-9._@/-]+$/;
+/** A path that climbs out of where it names: never a box path, whatever else is in it. */
+const climbs = (path) => path.split("/").includes("..");
 const ACCOUNT = /^(?:[a-z_][a-z0-9_-]{0,31}|\d{1,10})$/;
 const FLEET = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const UP = new Set(["creating", "pulling_snapshot", "pending_build", "building_snapshot", "starting", "restoring", "resuming", "resizing", "snapshotting", "forking", "stopping", "pausing", "paused"]);
@@ -152,6 +157,14 @@ export function sandboxName(prefix, runId, now) {
     return `${prefix}${slug}-${stamp}`.slice(0, 63);
 }
 /** The last line of a command's output that parses as JSON, or null. */
+/**
+ * What the launcher printed, for a start it gave no reason for: the last 4 KB, or that it printed nothing. It prints only
+ * its state; the mount token is in a root-only file it reads, never in its output.
+ */
+function launcherOutput(text) {
+    const out = text.trim();
+    return out ? `the launcher printed: ${out.slice(-4096)}` : "the launcher printed nothing and exited 0";
+}
 function lastJson(text) {
     for (const line of text.trim().split("\n").reverse()) {
         try {
@@ -185,7 +198,7 @@ export function daytonaHost(opts) {
     const now = opts.now ?? Date.now;
     const launch = opts.launcher ?? `${packageDir}/dist/hosts/daytona-launch.js`;
     for (const [what, value] of Object.entries({ mountRoot, node, packageDir, archil, boxDir: dir, stageDir: stage, launcher: launch })) {
-        if (!BOX_PATH.test(value))
+        if (!BOX_PATH.test(value) || climbs(value))
             throw new DaytonaHostError("INVALID_ARGUMENT", `${what} ${JSON.stringify(value)} is not a plain absolute path`);
     }
     if (!ACCOUNT.test(user) || !ACCOUNT.test(group))
@@ -246,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 = {
@@ -273,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,
@@ -288,7 +303,7 @@ export function daytonaHost(opts) {
                 const r = await run(box, launcher("start", name, left), Math.ceil(left / 1000) + 10, "starting the instance");
                 const state = lastJson(r.result);
                 if (!state || !(state.spawned > 0)) {
-                    throw new DaytonaHostError("START_FAILED", `the instance in ${name} did not start: ${state?.reason ?? r.result.trim().slice(0, 300)}`);
+                    throw new DaytonaHostError("START_FAILED", `the instance in ${name} did not start: ${state?.reason || launcherOutput(r.result)}`);
                 }
                 return handle;
             }
@@ -352,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,22 +50,28 @@ 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;
     });
 }
+/** The argv of that child for `path`. */
+export declare const statCodeArgv: (path: string) => string[];
 /** Exits a restart cannot fix: 65 data error, 70 store head unreadable, 75 fenced, 76 held. */
 export declare const TERMINAL_EXITS: readonly [65, 70, 75, 76];
 /** Minimal environment, a timeout that settles even if a grandchild keeps the pipes, and the input on stdin. */
 export declare const runCommand: Runner;
+/** This boot's id: `/proc/sys/kernel/random/boot_id`, or `kern.bootsessionuuid` on macOS. Throws when it cannot be read. */
 export declare function currentBootId(): string;
 /** `systemctl show` output as a map. */
 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;
 };
-/** Field 22 of /proc/<pid>/stat (start time in clock ticks), so a reused pid is never mistaken for the instance. */
+/**
+ * A live process's start (field 22 of /proc/<pid>/stat, in clock ticks; on macOS the second it started), so a reused pid is
+ * never mistaken for the instance. Null for a zombie, a process that is gone, or one the table cannot be read for.
+ */
 export declare function procStartTicks(pid: number): number | null;

package/dist/hosts/local-host.js

@@ -12,14 +12,15 @@
 // 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 { ARCHIL_SCOPED, DEAD_CONNECTION, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
 import { EXIT_FENCED, EXIT_HELD, PdaError } from "../errors.js";
 import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
+import { processTable, thisBoot } from "../process-table.js";
+import { attemptEnv } from "./attempt-env.js";
 export class LocalHostError extends PdaError {
     constructor(code, message, options = {}) {
         super(code, message, options);
@@ -32,7 +33,13 @@ 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";
+/**
+ * A stat of one path in a child process, so a stuck daemon never blocks this one: prints the errno code (or "ok"), never a
+ * message, which coreutils' `stat` prints in the locale's language.
+ */
+const STAT_CODE = `try { require("node:fs").statSync(process.argv[1]); process.stdout.write("ok"); } catch (e) { process.stdout.write(String(e.code)); process.exitCode = 1; }`;
+/** The argv of that child for `path`. */
+export const statCodeArgv = (path) => [process.execPath, "-e", STAT_CODE, path];
 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). */
@@ -63,8 +70,12 @@ export const runCommand = (argv, opts = {}) => new Promise((resolve, reject) =>
     child.stdin.on("error", () => { });
     child.stdin.end(opts.input ?? "");
 });
+/** This boot's id: `/proc/sys/kernel/random/boot_id`, or `kern.bootsessionuuid` on macOS. Throws when it cannot be read. */
 export function currentBootId() {
-    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const boot = thisBoot();
+    if (boot === null)
+        throw new Error("this machine's boot id cannot be read");
+    return boot;
 }
 const firstLine = (r) => (r.stderr.trim().split("\n").at(-1) ?? "").slice(0, 300);
 const okRan = (r) => r.code === 0 && !r.timedOut;
@@ -151,13 +162,13 @@ export function localHost(opts = {}) {
             return rm(path, { force: true });
         await root(["/bin/rm", "-f", path]);
     }
-    async function startUnit(ref, token) {
+    async function startUnit(ref, token, extra) {
         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 env = { ...opts.env, ...extra, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
         const path = tokenFile(unit);
         await writeTokenFile(path, token);
         let started = false;
@@ -192,7 +203,7 @@ export function localHost(opts = {}) {
             await (started ? emptyTokenFile(path) : removeFile(path)).catch(() => { });
         }
     }
-    async function startChild(ref, token) {
+    async function startChild(ref, token, extra) {
         const tag = `${prefix}${ref.id}-${Date.now().toString(36)}`;
         const mountpoint = mountpointOf(ref);
         const base = { driver: "local", mode: "child", host: hostName, bootId, mountpoint, tag };
@@ -201,7 +212,7 @@ export function localHost(opts = {}) {
             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 env = { ...opts.env, ...extra, 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);
@@ -234,13 +245,14 @@ export function localHost(opts = {}) {
             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.
+     * Whether the mount at `mp` is dead: its FUSE daemon is gone, so the stat fails with one of `DEAD_CONNECTION`'s codes
+     * (ENOTCONN, or ECONNABORTED for a stat in flight while the dying daemon's connection is torn down). The stat runs in a
+     * child with a timeout, so a live but stuck daemon never blocks this process, and the child prints the code, not a
+     * message; a stat that answers, fails otherwise 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);
+        const r = await exec(statCodeArgv(mp), { timeoutMs: STAT_TIMEOUT_MS });
+        return !r.timedOut && r.code !== 0 && DEAD_CONNECTION.has(r.stdout.trim());
     }
     /** Remove a dead mount: `fusermount -u`, then a lazy `umount -l`. The mount table, not an exit code, decides. */
     async function removeDeadMount(mp) {
@@ -277,9 +289,11 @@ export function localHost(opts = {}) {
     return {
         hostName,
         mountRoot,
-        start(ref, token) {
+        kills: "process",
+        async start(ref, token, attempt) {
             runPath(ref.id);
-            return mode === "systemd" ? startUnit(ref, token) : startChild(ref, token);
+            const extra = attemptEnv(attempt, (m) => new LocalHostError("INVALID_ARGUMENT", m));
+            return mode === "systemd" ? startUnit(ref, token, extra) : startChild(ref, token, extra);
         },
         async status(h) {
             if (!mine(h))
@@ -336,21 +350,44 @@ export function localHost(opts = {}) {
             await root([SYSTEMCTL, "reset-failed", `${h.unit}.service`]);
             await removeFile(tokenFile(h.unit));
         },
+        async kill(h) {
+            if (!mine(h) || h.bootId !== bootId)
+                return;
+            if (h.mode === "child") {
+                const pid = Number(h.pid);
+                // As in stop: only a real process, and only the one the handle names (its start ticks).
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number" || procStartTicks(pid) !== h.startTicks)
+                    return;
+                try {
+                    process.kill(-pid, "SIGKILL");
+                }
+                catch {
+                    // gone already
+                }
+                return;
+            }
+            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
+                return;
+            // Every process of the unit's control group at once, the instance's commands included. Its FUSE daemon runs in a
+            // scope of its own and keeps the mount, as after an OOM kill; the unit restarts in place unless restart is off.
+            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${h.unit}.service`]);
+            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+                throw new LocalHostError("KILL_FAILED", `systemctl kill ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+            }
+        },
     };
 }
-/** Field 22 of /proc/<pid>/stat (start time in clock ticks), so a reused pid is never mistaken for the instance. */
+/**
+ * A live process's start (field 22 of /proc/<pid>/stat, in clock ticks; on macOS the second it started), so a reused pid is
+ * never mistaken for the instance. Null for a zombie, a process that is gone, or one the table cannot be read for.
+ */
 export function procStartTicks(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
         return null;
-    let stat;
     try {
-        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        return processTable().snapshot().info(pid)?.start ?? null;
     }
     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

@@ -1,16 +1,35 @@
-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";
+export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
+export type { AfterClaim, BeforeResume, DurableRun, LeaseOptions, OpenDurableRunOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunEnv, RunErrorCode, RunLease, RunSeed, RunSeedDir, StoreHeadSource, StoreReads } from "./run.js";
+export { localRun } from "./local-run.js";
+export type { LocalRun } from "./local-run.js";
+export { CLAIM_UNMOUNTED, openClaimDir, readLocalRunStatus, RunRecordError } from "./status.js";
+export type { ClaimDir, OpenClaimDirOptions, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";
+export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
+export type { ArchilEnvClaim, ArchilEnvFactory, ArchilEnvOptions, EnvErrorCode } from "./env.js";
+export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
+export type { AcquireOptions, ArchilHost, Claim, ControlApi, PathlessResolver, RunRef, Unmounted } from "./claim.js";
+export { readReleased, withClaim } from "./with-claim.js";
+export type { ClaimControl, HeldPath, WithClaimOptions } from "./with-claim.js";
+export { PathOutsideWorkError } from "./confine.js";
+export type { RefusalReason } from "./confine.js";
+export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
+export type { ClaimErrorCode, Holder } from "./errors.js";
+export type { ArchilStore, Fence, FencedDatabase, Profile, StoreFencedError } from "./store.js";
+export { AppError } from "./app.js";
+export type { AppContext, AppModule, AppOptions } from "./app.js";
+export { archilControl, deleteRunTree, ensureRunning, readRunStatus, SuperviseError } from "./supervise.js";
+export type { ArchilControl, CheckControl, CheckOptions, DiskClient, EnsureOptions, EnsureResult, HostDriver, HostHandle, HostStatus, Json, StartAttempt, StartReason, StonithOutcome, SuperviseErrorCode, SupervisorControl, TokenUser } from "./supervise.js";
+export { localHost, LocalHostError } from "./hosts/local-host.js";
+export type { LocalHostOptions, Ran, Runner } from "./hosts/local-host.js";
+export { dockerHost, DockerHostError } from "./hosts/docker.js";
+export type { ContainerInfo, DockerHostOptions, DockerRan, DockerRunner } from "./hosts/docker.js";
+export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./hosts/daytona.js";
+export type { CreateSandboxBody, DaytonaClient, DaytonaHostErrorCode, DaytonaHostOptions, DaytonaRestOptions, ExecResult, SandboxInfo } from "./hosts/daytona.js";
+export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
+export type { RequestOptions, RunResponse, RunServer, ServeConfigErrorCode, ServeErrorCode, ServeOptions } from "./serve.js";
+export { archilPlace, localPlace, PlaceError } from "./place.js";
+export type { ArchilPlaceOptions, LocalPlaceOptions, Place, PlaceContext, PlaceErrorCode, PlaceExit, PlaceKill, PlaceOutcome, PlacePaths, PlaceRecovery, PlaceRunner, PlaceSignal, PlaceStatus, RunnerOrder } from "./place.js";
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
+export type { BusyState, DrainOptions, Parking, ParkOptions, ParkResult, ParkTarget } from "./park.js";
+export { fork, ForkError, forkLocal } from "./fork.js";
+export type { ForkErrorCode, ForkLocalResult, ForkOptions, ForkResult } from "./fork.js";

package/dist/index.js

@@ -1,17 +1,28 @@
-// Public API.
-export * from "./app.js";
-export * from "./claim.js";
+// The package's public API. Every name is listed: a new export is a reviewed line here, and test/entries.test.ts pins the
+// list of each entry. `./lease` is the narrow entry for a host that owns its Harness; `./internals` holds plumbing that
+// examples and demos use, with no compatibility promise.
+// The run: open it, on a disk or a local directory, with its environment, its claim and the errors it fails with.
+export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
+export { localRun } from "./local-run.js";
+export { CLAIM_UNMOUNTED, openClaimDir, readLocalRunStatus, RunRecordError } from "./status.js";
+export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
+export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
+// A short exclusive claim on any path of a disk, and a consistent S3 read of a released file (an agent home beside the runs).
+export { readReleased, withClaim } from "./with-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";
+export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
+// The app contract: what `--app` names.
+export { AppError } from "./app.js";
+// The supervisor and the host drivers.
+export { archilControl, deleteRunTree, ensureRunning, readRunStatus, SuperviseError } from "./supervise.js";
+export { localHost, LocalHostError } from "./hosts/local-host.js";
+export { dockerHost, DockerHostError } from "./hosts/docker.js";
+export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./hosts/daytona.js";
+// Serve: one HTTP request runs one turn.
+export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
+// Places: where a run lives for a supervisor that kills it and brings it back (agentrun's reference place seam).
+export { archilPlace, localPlace, PlaceError } from "./place.js";
+// Parking: an idle run gives its host back.
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
+// Fork: a new run from a run's committed state.
+export { fork, ForkError, forkLocal } from "./fork.js";

package/dist/internals.d.ts

@@ -0,0 +1,3 @@
+export { createRunDir, findDelegations, mintMountToken, pathlessResolver, removeMountToken, runPath, unmountClaim } from "./claim.js";
+export { LABEL_FLEET, LABEL_RUN, sandboxName, sandboxStatus, sweepSandboxes } from "./hosts/daytona.js";
+export { isLeaseFresh, parseRunRecord, RUN_JSON } from "./status.js";

package/dist/internals.js

@@ -0,0 +1,6 @@
+// `@parcha/pi-durable-disk/internals`: the claim, status and Daytona plumbing that this repository's examples and demos
+// use. No compatibility promise: a name here may change or go in any release, and the CHANGELOG says when. A name moves
+// to the root entry when something outside this repository needs it.
+export { createRunDir, findDelegations, mintMountToken, pathlessResolver, removeMountToken, runPath, unmountClaim } from "./claim.js";
+export { LABEL_FLEET, LABEL_RUN, sandboxName, sandboxStatus, sweepSandboxes } from "./hosts/daytona.js";
+export { isLeaseFresh, parseRunRecord, RUN_JSON } from "./status.js";