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

package/dist/confine.js

@@ -10,8 +10,14 @@
 // openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS) done in user space. Node has no openat, so a handle's directory is named
 // `/proc/self/fd/<fd>`: the kernel jumps straight to the held inode there and never re-walks the directory's own path. A
 // swapped component fails the open (ELOOP or ENOTDIR) and the call is refused as changed; nothing is retried.
+//
+// macOS has no /proc/self/fd, so there (`byPath`) each step is opened by its full path, still with O_NOFOLLOW, and the
+// walk ends by checking that the path still resolves to itself and names the directory held (same device and inode). A
+// component that is a symlink, or was swapped for one before that check, is refused as changed. The operation then
+// names the path again, so a command that swaps a directory above the target between the check and the operation can
+// win: by path, the confinement holds against an agent's paths and the links already in place, not a command racing it.
 import { constants, existsSync, realpathSync } from "node:fs";
-import { lstat, mkdir, open, readlink, realpath } from "node:fs/promises";
+import { lstat, mkdir, open, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { err, FileError, ok } from "@earendil-works/pi-durable/env";
 /**
@@ -119,8 +125,9 @@ export const inside = (path, root) => path === root || path.startsWith(root.ends
 const FILE_INFO_KEYS = ["name", "path", "kind", "size", "mtimeMs"];
 const isFileInfo = (value) => typeof value === "object" && value !== null && FILE_INFO_KEYS.every((key) => key in value) && typeof value.path === "string";
 /**
- * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths to hand to pi's own implementation; every
- * path and message it returns is mapped back to the real one with `restore`. Close it when the operation is done.
+ * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths (by path, the real ones) to hand to pi's
+ * own implementation; every path and message it returns is mapped back to the real one with `restore`. Close it when
+ * the operation is done.
  */
 export class Pin {
     canonical;
@@ -134,17 +141,29 @@ export class Pin {
     /** What `dir` stands for: the directory itself, or the directory holding the entry. */
     #real;
     #closed = false;
-    constructor(handle, canonical, name, dirMode) {
+    #byPath;
+    #names;
+    /**
+     * `held` is the walk's: whether it went by path, and then the held directory's real path; and the names of the
+     * confinement's roots (`Confinement`'s `names`).
+     */
+    constructor(handle, canonical, name, dirMode, held = { byPath: false, path: "" }) {
         this.#handle = handle;
         this.canonical = canonical;
         this.name = name;
-        this.dir = `/proc/self/fd/${handle.fd}`;
+        this.#byPath = held.byPath;
+        this.#names = held.names ?? [];
+        this.dir = held.byPath ? held.path : `/proc/self/fd/${handle.fd}`;
         this.entry = dirMode ? this.dir : name === "" ? `${this.dir}/.` : `${this.dir}/${name}`;
         this.#real = dirMode || name === "" ? canonical : dirname(canonical);
     }
-    /** `text` with the held paths replaced by the real ones. */
+    /** `text` with the held paths replaced by the real ones, and a root named as the caller names it. */
     translate(text) {
-        return text.split(this.entry).join(this.canonical).split(this.dir).join(this.#real);
+        let real = text.split(this.entry).join(this.canonical).split(this.dir).join(this.#real);
+        // A function, so `$&` or `$$` in the name is kept as written rather than expanded.
+        for (const { canonical, named } of this.#names)
+            real = real.replace(canonical, () => named);
+        return real;
     }
     /** An error pi or Node raised on a held path, as a FileError that names the real one. */
     error(error, path) {
@@ -169,16 +188,25 @@ export class Pin {
         }
         return value;
     }
-    /** Opens the target's last component, which is never followed, and returns its handle; the caller closes it. */
+    /**
+     * Opens the target's last component, which is never followed, and returns its handle; the caller closes it. By path,
+     * the directory's path must still name the directory held once the file is open.
+     */
     async openFile(flags, mode) {
+        let file;
         try {
-            return await open(this.entry, flags | FILE, mode);
+            file = await open(this.entry, flags | FILE, mode);
         }
         catch (error) {
             if (errno(error) === "ELOOP")
                 throw changed(this.canonical);
             throw error;
         }
+        if (this.#byPath && !(await namesHeld(this.dir, this.#handle))) {
+            await file.close().catch(() => undefined);
+            throw changed(this.canonical);
+        }
+        return file;
     }
     binaryReader(reader) {
         return {
@@ -213,12 +241,24 @@ const changed = (path) => new PathOutsideWorkError(path, "changed", `${path}: a
 export class Confinement {
     work;
     readOnly;
+    /** Whether the walk goes by path (macOS, which has no `/proc/self/fd`; see the top of this file). */
+    byPath;
     /** Directories handed out for writing after construction (the environment's temp dirs), canonical. */
     #handed = new Set();
-    /** Canonical directories: `work` may be read and written, `readOnly` only read. */
-    constructor(work, readOnly) {
+    #names;
+    /**
+     * Canonical directories: `work` may be read and written, `readOnly` only read. `byPath` defaults to true on macOS only.
+     * `names` maps a canonical root to the path the caller names it by, where they differ (a root under a symlinked
+     * directory, as `/tmp` and `/var` are on macOS): results name paths under it as the caller does, as pi's own do.
+     */
+    constructor(work, readOnly, options = {}) {
         this.work = work;
         this.readOnly = readOnly;
+        this.byPath = options.byPath ?? process.platform === "darwin";
+        // Longest first, so a root inside another is named before the outer one could take its prefix.
+        this.#names = [...(options.names ?? [])]
+            .sort(([a], [b]) => b.length - a.length)
+            .map(([canonical, named]) => ({ canonical: new RegExp(`${canonical.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![^/'"\\s,;:)\\]])`, "g"), named }));
     }
     /**
      * Lets file operations write inside `dir` too: a directory this process just created (`createTempDir`) directly in a
@@ -257,18 +297,18 @@ export class Confinement {
             const holder = this.#handed.has(root) ? this.readOnly.find((candidate) => dirname(root) === candidate) : undefined;
             if (holder === undefined)
                 throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
-            return new Pin(await walk(holder, [], "none", canonical), canonical, basename(root), false);
+            return new Pin(await walk(holder, [], "none", canonical, this.byPath), canonical, basename(root), false, { byPath: this.byPath, path: holder, names: this.#names });
         }
         const name = names.pop() ?? "";
-        const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical);
-        return new Pin(handle, canonical, name, false);
+        const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical, this.byPath);
+        return new Pin(handle, canonical, name, false, { byPath: this.byPath, path: join(root, ...names), names: this.#names });
     }
     /** Pins the target directory itself; `create` makes it and the directories above it when they are missing. */
     async pinDir(abs, original, spec) {
         const { canonical, root } = await this.locate(abs, original, spec.access, true);
         await confineHooks.afterCheck?.(canonical);
-        const handle = await walk(root, relative(root, canonical), spec.create === true ? "all" : "none", canonical);
-        return new Pin(handle, canonical, basename(canonical), true);
+        const handle = await walk(root, relative(root, canonical), spec.create === true ? "all" : "none", canonical, this.byPath);
+        return new Pin(handle, canonical, basename(canonical), true, { byPath: this.byPath, path: canonical, names: this.#names });
     }
 }
 const relative = (root, path) => (path === root ? [] : path.slice(root.length + (root.endsWith("/") ? 0 : 1)).split("/"));
@@ -286,8 +326,23 @@ async function swapped(error, path) {
         return false;
     return (await lstat(path).catch(() => undefined))?.isSymbolicLink() === true;
 }
-/** Opens `root`, then each name below it, every step relative to the handle before it and without following links. */
-async function walk(root, names, create, canonical) {
+/** Whether `path` still names the directory `held` holds (same device and inode); false when it cannot be read. */
+export async function namesHeld(path, held) {
+    try {
+        const [named, opened] = await Promise.all([stat(path, { bigint: true }), held.stat({ bigint: true })]);
+        return named.dev === opened.dev && named.ino === opened.ino;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Opens `root`, then each name below it, every step relative to the handle before it and without following links. By
+ * path, every step is opened by its full path instead, and the last must then resolve to itself and be the one held.
+ */
+async function walk(root, names, create, canonical, byPath = false) {
+    if (byPath)
+        return walkByPath(root, names, create, canonical);
     let dir;
     try {
         dir = await open(root, DIRECTORY);
@@ -339,3 +394,55 @@ async function walk(root, names, create, canonical) {
         throw error;
     }
 }
+async function walkByPath(root, names, create, canonical) {
+    let real = root;
+    let dir;
+    try {
+        dir = await open(root, DIRECTORY);
+    }
+    catch (error) {
+        if (await swapped(error, root))
+            throw changed(canonical);
+        throw error;
+    }
+    try {
+        for (const name of names) {
+            if (name === "" || name === "." || name === ".." || name.includes("\0"))
+                throw changed(canonical);
+            real = join(real, name);
+            let next;
+            try {
+                next = await open(real, DIRECTORY);
+            }
+            catch (error) {
+                if (create === "all" && errno(error) === "ENOENT") {
+                    await mkdir(real).catch((made) => {
+                        if (errno(made) !== "EEXIST")
+                            throw made;
+                    });
+                    next = await open(real, DIRECTORY).catch(async (opened) => {
+                        throw (await swapped(opened, real)) ? changed(canonical) : opened;
+                    });
+                }
+                else if (await swapped(error, real)) {
+                    throw changed(canonical);
+                }
+                else {
+                    throw error;
+                }
+            }
+            await dir.close();
+            dir = next;
+        }
+        // Each step was opened by its full path, and only the last component of each open is never followed: the path must
+        // still resolve to itself (no component above is a link) and name the directory held (none was swapped and back).
+        const resolved = await realpath(real).catch(() => undefined);
+        if (resolved !== real || !(await namesHeld(real, dir)))
+            throw changed(canonical);
+        return dir;
+    }
+    catch (error) {
+        await dir.close().catch(() => undefined);
+        throw error;
+    }
+}

package/dist/env.d.ts

@@ -1,9 +1,8 @@
 import type { Context } from "@earendil-works/chord";
-import type { Extension, ToolHooks, ToolRegistration } from "@earendil-works/pi-durable";
+import type { Extension, ToolRegistration } from "@earendil-works/pi-durable";
 import { ExecutionError } from "@earendil-works/pi-durable/env";
 import { NodeExecutionEnv, type NodeWatchOptions } from "@earendil-works/pi-durable/env/node";
 import { PdaError } from "./errors.js";
-type ToolCall = Parameters<ToolHooks["afterTool"]>[0];
 /** What the environment needs of a claim; the claim satisfies it structurally. */
 export interface ArchilEnvClaim {
     /** Absolute mount path of the run directory; the same on every host that claims the run. */
@@ -26,15 +25,17 @@ export interface ArchilEnvOptions {
     /**
      * Run every command with no_new_privs (`setpriv --no-new-privs --`): setuid programs and file capabilities stop
      * granting privilege, so a command cannot `sudo` even when the run user has a sudo rule (the host needs one for the
-     * archil verbs). Default true. Set false on a host that already confines commands, or where util-linux is absent.
+     * archil verbs). Default true, but false on macOS, which has no no_new_privs: there a command keeps the user's rights,
+     * sudo included. Set false on a host that already confines commands, or where util-linux is absent.
      */
     readonly noNewPrivs?: boolean;
     /** The util-linux `setpriv` that `noNewPrivs` and `runAs` run; default `/usr/bin/setpriv`. */
     readonly setprivPath?: string;
     /**
      * Confine every file operation to the workspace (`PathOutsideWorkError` otherwise): read, write, edit and every other
-     * path pi's file system takes. Default true. Set false only where the paths are confined some other way, or where
-     * `/proc/self/fd` is unavailable (the confinement walks paths through it).
+     * path pi's file system takes. Default true. On macOS, which has no `/proc/self/fd`, the confinement walks paths by
+     * name instead, and holds against an agent's paths and the links in place, not a command racing it (confine.ts). Set
+     * false only where the paths are confined some other way, or where `/proc/self/fd` is unavailable on Linux.
      */
     readonly confineFiles?: boolean;
     /**
@@ -99,7 +100,7 @@ export interface ArchilEnvFactory {
 export declare function archilEnv(claim: ArchilEnvClaim, options?: ArchilEnvOptions): ArchilEnvFactory;
 /** Built-in tools that only read. A tool in this set is declared `replay: "safe"`. */
 export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
-/** Built-in tools that can change the workspace; their results follow the workspace barrier. */
+/** Built-in tools that can change the workspace; none of them is declared replay-safe. */
 export declare const WRITING_TOOLS: ReadonlySet<string>;
 /** The tool declared `replay: "safe"`: an interrupted call reruns on recovery instead of reporting `interrupted`. */
 export declare function replaySafe<T extends ToolRegistration>(tool: T): T;
@@ -111,19 +112,3 @@ export declare function markReadOnlySafe<T extends ToolRegistration>(tools: read
  * grep; an app that adds them declares them safe with `markReadOnlySafe`.
  */
 export declare const ArchilCodingTools: Extension;
-export interface WorkspaceBarrierOptions {
-    /** Tools whose result follows a barrier; default `WRITING_TOOLS`. An app adds its own writing tools here. */
-    readonly tools?: Iterable<string>;
-}
-/**
- * The hook point for the rule that the workspace changes a tool made are durable before its result is committed.
- * Install this extension only when the result commit's own fsync does not already satisfy the rule; with it
- * not installed nothing runs. `barrier` is the claim's (`claim.barrier()`), called after a writing tool ran and before
- * pi appends its result entry, for the calls whose tool name is in `options.tools`.
- *
- * pi reports and ignores an `afterTool` hook that throws, so a failed barrier cannot hold the result back by throwing.
- * It replaces the result with an error result carrying the diagnostic `workspace_not_durable`: a success never commits
- * for a workspace that is not durable. The host decides separately whether a failed barrier means the claim is fenced.
- */
-export declare function workspaceBarrier(barrier: (call: ToolCall, context: Context) => Promise<void>, options?: WorkspaceBarrierOptions): Extension;
-export {};

package/dist/env.js

@@ -1,18 +1,18 @@
 // The execution environment: pi's NodeExecutionEnv rooted at the run's work/ directory, with an environment id
 // that names the run, commands that cannot gain privilege (no_new_privs), optionally commands run as another user
 // (`runAs`, for an instance that runs as root in a container), file operations confined to work/ (confine.ts),
-// read-only built-in tools declared replay-safe, and the hook point for the workspace barrier. Tools run
-// on the host that holds the claim, against the claimed mount.
+// and read-only built-in tools declared replay-safe. Tools run on the host that holds the claim, against the claimed
+// mount.
 import { accessSync, constants, existsSync, statSync } from "node:fs";
 import { access, chmod, lchown, lstat, mkdir, mkdtemp, open, realpath, stat } from "node:fs/promises";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { withAbortSignal } from "@earendil-works/chord/context";
-import { defineExtension, hook, ToolTask } from "@earendil-works/pi-durable";
+import { defineExtension } from "@earendil-works/pi-durable";
 import { err, ExecutionError, FileError, getOrThrow, ok } from "@earendil-works/pi-durable/env";
 import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
 import { CodingTools } from "@earendil-works/pi-durable/tools";
 import { COMMANDS_MARK, CommandRecorder } from "./commands.js";
-import { canonicalizeSync, confineHooks, Confinement, fileError, inside } from "./confine.js";
+import { canonicalizeSync, confineHooks, Confinement, fileError, inside, namesHeld, PathOutsideWorkError } from "./confine.js";
 import { PdaError } from "./errors.js";
 /**
  * What `exec` returns once the factory's `cleanup()` ran: no command was started. Its `code` is pi's `spawn_error`
@@ -130,7 +130,7 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
         return this.#entry(path, context, { access: spec.access, follow: true, ...(spec.parents ? { parents: true } : {}) }, async (pin) => {
             const handle = await pin.openFile(spec.flags);
             try {
-                return await run(handle);
+                return await run(handle, pin);
             }
             finally {
                 await handle.close().catch(() => undefined);
@@ -150,8 +150,10 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
     async openTextLineReader(path, context) {
         if (this.#scope.confinement === undefined)
             return super.openTextLineReader(path, context);
-        // pi opens the file again through the handle's own `/proc/self/fd` entry, which names that inode and no path.
-        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle) => super.openTextLineReader(`/proc/self/fd/${handle.fd}`, context));
+        // pi opens the file again through the handle's own `/proc/self/fd` entry, which names that inode and no path; by path
+        // (macOS), through the path just checked.
+        const byPath = this.#scope.confinement.byPath;
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle, pin) => super.openTextLineReader(byPath ? pin.entry : `/proc/self/fd/${handle.fd}`, context));
     }
     async openBinaryReader(path, options, context) {
         if (this.#scope.confinement === undefined)
@@ -309,7 +311,10 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
             const held = await open(tempRoot, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
             let name;
             try {
-                name = basename(await mkdtemp(`/proc/self/fd/${held.fd}/${prefix ?? "tmp-"}`));
+                // By path (macOS): made under tmp/'s path once that path is checked to still name the directory held.
+                if (confinement.byPath && !(await namesHeld(tempRoot, held)))
+                    throw new PathOutsideWorkError(tempRoot, "changed", `${tempRoot}: changed while it was being resolved`);
+                name = basename(await mkdtemp(`${confinement.byPath ? tempRoot : `/proc/self/fd/${held.fd}`}/${prefix ?? "tmp-"}`));
             }
             finally {
                 await held.close();
@@ -485,13 +490,17 @@ function requireSetpriv(path) {
  * Taken at construction, before any agent runs, so a symlink an agent puts in place of `work` or `tmp` later cannot widen
  * them: it resolves outside the roots and is refused.
  */
-function requireConfinement(claim, readRoots) {
-    if (!existsSync("/proc/self/fd")) {
+function requireConfinement(claim, readRoots, byPath) {
+    if (!byPath && !existsSync("/proc/self/fd")) {
         throw new EnvError("PROC_UNAVAILABLE", "file operations are confined by walking paths through /proc/self/fd, which is not available here. " +
             "Mount /proc, or pass confineFiles: false where the file paths are confined some other way.");
     }
-    const tmp = join(canonicalizeSync(claim.root), TEMP_DIR);
-    return new Confinement(canonicalizeSync(claim.work), [tmp, ...readRoots.map((root) => canonicalizeSync(root))]);
+    // Each root as the caller names it, where that differs from its canonical path (under /tmp or /var on macOS).
+    const names = new Map();
+    const named = (canonical, as) => (canonical === as ? canonical : (names.set(canonical, as), canonical));
+    const tmp = named(join(canonicalizeSync(claim.root), TEMP_DIR), join(claim.root, TEMP_DIR));
+    const work = named(canonicalizeSync(claim.work), claim.work);
+    return new Confinement(work, [tmp, ...readRoots.map((root) => named(canonicalizeSync(root), root))], { byPath, names });
 }
 export function archilEnv(claim, options = {}) {
     const id = ["archil", claim.disk, claim.root].filter((part) => part !== undefined && part !== "").join(":");
@@ -500,9 +509,10 @@ export function archilEnv(claim, options = {}) {
     if (runAs && ![runAs.uid, runAs.gid].every((n) => Number.isSafeInteger(n) && n >= 0)) {
         throw new EnvError("INVALID_RUN_AS", `runAs needs a numeric uid and gid, got ${JSON.stringify(runAs)}`);
     }
-    const noNewPrivs = options.noNewPrivs !== false;
+    const darwin = process.platform === "darwin";
+    const noNewPrivs = options.noNewPrivs ?? !darwin;
     const setpriv = noNewPrivs || runAs ? requireSetpriv(options.setprivPath ?? SETPRIV) : undefined;
-    const confinement = options.confineFiles === false ? undefined : requireConfinement(claim, options.readRoots ?? []);
+    const confinement = options.confineFiles === false ? undefined : requireConfinement(claim, options.readRoots ?? [], darwin);
     const scope = {
         id,
         tempRoot: join(claim.root, TEMP_DIR),
@@ -542,7 +552,7 @@ export function archilEnv(claim, options = {}) {
 }
 /** Built-in tools that only read. A tool in this set is declared `replay: "safe"`. */
 export const READ_ONLY_TOOLS = new Set(["read", "ls", "find", "grep"]);
-/** Built-in tools that can change the workspace; their results follow the workspace barrier. */
+/** Built-in tools that can change the workspace; none of them is declared replay-safe. */
 export const WRITING_TOOLS = new Set(["write", "edit", "bash", "powershell"]);
 /** The tool declared `replay: "safe"`: an interrupted call reruns on recovery instead of reporting `interrupted`. */
 export function replaySafe(tool) {
@@ -561,48 +571,3 @@ export const ArchilCodingTools = defineExtension({
     name: CodingTools.name,
     tools: markReadOnlySafe(CodingTools.tools ?? []),
 });
-/**
- * The hook point for the rule that the workspace changes a tool made are durable before its result is committed.
- * Install this extension only when the result commit's own fsync does not already satisfy the rule; with it
- * not installed nothing runs. `barrier` is the claim's (`claim.barrier()`), called after a writing tool ran and before
- * pi appends its result entry, for the calls whose tool name is in `options.tools`.
- *
- * pi reports and ignores an `afterTool` hook that throws, so a failed barrier cannot hold the result back by throwing.
- * It replaces the result with an error result carrying the diagnostic `workspace_not_durable`: a success never commits
- * for a workspace that is not durable. The host decides separately whether a failed barrier means the claim is fenced.
- */
-export function workspaceBarrier(barrier, options = {}) {
-    const writing = new Set(options.tools ?? WRITING_TOOLS);
-    return defineExtension({
-        name: "archil-workspace-barrier",
-        hooks: [
-            hook(ToolTask, {
-                afterTool: async (call, result, _api, context) => {
-                    if (!writing.has(call.name))
-                        return undefined;
-                    try {
-                        await barrier(call, context);
-                        return undefined;
-                    }
-                    catch (error) {
-                        // An aborted invocation must propagate: pi rethrows hook errors only while it is aborted.
-                        if (context.abortSignal?.aborted)
-                            throw error;
-                        return notDurable(result, error);
-                    }
-                },
-            }),
-        ],
-    });
-}
-function notDurable(result, error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    return {
-        ...result,
-        isError: true,
-        diagnostics: [
-            ...(result.diagnostics ?? []),
-            { severity: "error", code: "workspace_not_durable", message: `The workspace could not be made durable: ${reason}` },
-        ],
-    };
-}

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/fork.d.ts

@@ -39,3 +39,26 @@ export type ForkResult = {
  * and mount of its own is removed either way.
  */
 export declare function fork(ref: RunRef, newId: string, options: ForkOptions): Promise<ForkResult>;
+export interface ForkLocalResult {
+    /** The new run's id, and the directory it lives in. */
+    readonly run: string;
+    readonly root: string;
+    readonly from: string;
+    readonly sealedSeq: number;
+    readonly sourceGeneration: number;
+    readonly files: number;
+    readonly bytes: number;
+}
+/**
+ * Fork a run on a local directory (`localRun`) into one new run directory per entry of `into`: the same copy as `fork`, for
+ * one machine and without a disk. `from` must hold a released, sealed run (run.json paused, sleeping, done or failed with a
+ * `sealedSeq`); anything else is `SOURCE_NOT_RELEASED`, and no target may exist (`TARGET_EXISTS`). The source is only read.
+ * Every copy is made beside its target under a temporary name and none is published until all are complete, so a failed
+ * batch leaves nothing behind and never takes back a run another process opened; each opens as
+ * generation 1 of a run of its own, refusing a copy that lost a committed sequence like any fork. Nothing guards a source
+ * that another process is opening at the same moment: a local directory has no mount to take it exclusively.
+ */
+export declare function forkLocal(from: string, into: readonly {
+    readonly id: string;
+    readonly root: string;
+}[]): Promise<ForkLocalResult[]>;

package/dist/fork.js

@@ -3,8 +3,9 @@
 // root of their own, never where an instance mounts. The source is only read (its claim probe aside, which every mount
 // writes). The new run's run.json starts at generation 0 and carries the source's seal: its first open is generation 1
 // and refuses a copy that lost a committed sequence (STORE_BEHIND_SEAL). Supervisor side: it needs the API key.
-import { chmod, copyFile, lchown, lstat, mkdir, readdir, readlink, rm, rmdir, symlink, utimes } from "node:fs/promises";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { chmod, copyFile, lchown, lstat, mkdir, readdir, readlink, realpath, rename, rm, rmdir, symlink, utimes } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { acquire, createRunDir, findDelegations, mintMountToken, removeMountToken, runPath } from "./claim.js";
 import { HeldError, PdaError } from "./errors.js";
 import { persistRecord, readRunRecord, RUN_JSON, RUN_JSON_TEMP } from "./status.js";
@@ -16,7 +17,7 @@ const RELEASED = ["paused", "sleeping", "done", "failed"];
  * Not copied: the run's own lifecycle files (the fork writes its own run.json), the supervisor's start mark (copied, it
  * would hold the new run in a start grace for a start that never happened), and the scratch directory.
  */
-const SKIP = new Set([RUN_JSON, RUN_JSON_TEMP, OWNER_LOCK, `${OWNER_LOCK}-journal`, ".claim", START_MARK, "tmp"]);
+const SKIP = new Set([RUN_JSON, RUN_JSON_TEMP, OWNER_LOCK, `${OWNER_LOCK}-journal`, ".claim", START_MARK, "tmp", "commands"]);
 export class ForkError extends PdaError {
     constructor(code, message, options = {}) {
         super(code, message, options);
@@ -179,3 +180,102 @@ export async function fork(ref, newId, options) {
         await rmdir(base).catch(() => { });
     }
 }
+/**
+ * Fork a run on a local directory (`localRun`) into one new run directory per entry of `into`: the same copy as `fork`, for
+ * one machine and without a disk. `from` must hold a released, sealed run (run.json paused, sleeping, done or failed with a
+ * `sealedSeq`); anything else is `SOURCE_NOT_RELEASED`, and no target may exist (`TARGET_EXISTS`). The source is only read.
+ * Every copy is made beside its target under a temporary name and none is published until all are complete, so a failed
+ * batch leaves nothing behind and never takes back a run another process opened; each opens as
+ * generation 1 of a run of its own, refusing a copy that lost a committed sequence like any fork. Nothing guards a source
+ * that another process is opening at the same moment: a local directory has no mount to take it exclusively.
+ */
+export async function forkLocal(from, into) {
+    for (const t of into)
+        runPath(t.id); // a run id the disk would refuse is refused here too
+    const source = await realpath(resolve(from)).catch(() => resolve(from));
+    const targets = await Promise.all(into.map(async (t) => ({ id: t.id, root: await resolvedPath(t.root) })));
+    if (targets.length === 0)
+        throw new ForkError("INVALID_ARGUMENT", "forkLocal needs at least one target");
+    // Two targets the same, or one beneath another (`/runs/a` and `/runs/a/b`): staging the inner one would make the outer one's directory.
+    if (targets.some((t, i) => targets.some((u, j) => i !== j && (t.root === u.root || t.root.startsWith(`${u.root}${sep}`))))) {
+        throw new ForkError("INVALID_ARGUMENT", "two targets are the same directory, or one is inside another");
+    }
+    // A target inside the source (by a symlink too) would be copied into itself and would write into a source that is only read.
+    if (targets.some((t) => t.root === source || t.root.startsWith(`${source}${sep}`)))
+        throw new ForkError("INVALID_ARGUMENT", "a fork needs a directory of its own, outside the source");
+    const record = await readRunRecord(source).catch((cause) => {
+        throw new ForkError("SOURCE_NOT_RELEASED", `${source} holds no readable run.json`, { cause });
+    });
+    if (!record || !RELEASED.includes(record.status) || record.sealedSeq === null) {
+        throw new ForkError("SOURCE_NOT_RELEASED", `the run in ${source} is not released and sealed (${record ? `${record.status}, sealedSeq ${record.sealedSeq}` : "no run.json"})`);
+    }
+    if (targets.some((t) => t.id === record.run))
+        throw new ForkError("INVALID_ARGUMENT", "a fork needs a new run id");
+    for (const t of targets) {
+        if (await lstat(t.root).then(() => true, () => false))
+            throw new ForkError("TARGET_EXISTS", `${t.root} already exists`);
+    }
+    const asRoot = process.getuid?.() === 0;
+    const st = await lstat(source);
+    // Every copy is made beside its target under a temporary name and none is published until all are complete: a failed
+    // batch removes only temporary directories, never a run another process could already have opened.
+    const staged = [];
+    const published = [];
+    try {
+        for (const t of targets) {
+            const temp = `${t.root}.fork-${randomUUID()}`; // unique per call: two forks of one target never share a temporary directory
+            const entry = { ...t, temp, files: 0, bytes: 0 };
+            await mkdir(dirname(t.root), { recursive: true });
+            await mkdir(temp);
+            staged.push(entry); // tracked for cleanup only once this call made it
+            const count = { files: 0, bytes: 0 };
+            await copyTree(source, temp, true, asRoot, count);
+            Object.assign(entry, count);
+            const forked = {
+                run: t.id,
+                status: "paused",
+                generation: 0,
+                sealedSeq: record.sealedSeq,
+                wakeAt: null,
+                holder: null,
+                heartbeatAt: null,
+                updatedAt: new Date().toISOString(),
+                detail: { forkedFrom: { run: record.run, generation: record.generation, sealedSeq: record.sealedSeq } },
+            };
+            await persistRecord(temp, `${JSON.stringify(forked, null, 2)}\n`);
+            // The run's directory is the source's: its owner and mode, so whoever owned the source can open the fork.
+            if (asRoot)
+                await lchown(temp, st.uid, st.gid);
+            await chmod(temp, st.mode & 0o7777);
+        }
+        for (const entry of staged) {
+            await rename(entry.temp, entry.root);
+            published.push(entry.root);
+        }
+    }
+    catch (error) {
+        for (const entry of staged)
+            await rm(entry.temp, { recursive: true, force: true }).catch(() => undefined);
+        // Only a copy no one has opened is taken back: an owner lock means a process already runs it.
+        for (const root of published)
+            if (!(await lstat(join(root, OWNER_LOCK)).then(() => true, () => false)))
+                await rm(root, { recursive: true, force: true }).catch(() => undefined);
+        throw error instanceof ForkError ? error : new ForkError("COPY_FAILED", `forking ${source} failed: ${error.message}`, { cause: error });
+    }
+    return staged.map((t) => ({ run: t.id, root: t.root, from: record.run, sealedSeq: record.sealedSeq, sourceGeneration: record.generation, files: t.files, bytes: t.bytes }));
+}
+/** `path` made absolute with every symlink of its existing part resolved, so two spellings of one place compare equal. */
+async function resolvedPath(path) {
+    const absolute = resolve(path);
+    const missing = [];
+    for (let at = absolute;; at = dirname(at)) {
+        try {
+            return join(await realpath(at), ...missing.reverse());
+        }
+        catch {
+            if (dirname(at) === at)
+                return absolute;
+            missing.push(basename(at));
+        }
+    }
+}

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.d.ts

@@ -42,7 +42,9 @@ export type LaunchStatus = {
     instanceAlive: boolean;
 };
 export declare function readState(dir: string, name: string): LaunchState | null;
-/** 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 declare function launchStatus(dir: string, name: string): LaunchStatus;
 /** The loop `serve` runs; resolves with the final state. */
 export declare function serve(dir: string, name: string): Promise<LaunchState>;