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

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. */
@@ -12,6 +11,11 @@ export interface ArchilEnvClaim {
     readonly work: string;
     /** The disk's id; part of the environment id when present. */
     readonly disk?: string;
+    /**
+     * Where the commands this environment starts are recorded, so that the next open of the claim ends what a killed
+     * incarnation left running (`reapCommands`). Set by a claim that nothing else cleans up after: a local run's.
+     */
+    readonly commands?: string;
 }
 export interface ArchilEnvOptions {
     /** How `watch` runs. Polling is the default because a FUSE mount does not report changes made elsewhere. */
@@ -21,21 +25,23 @@ 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;
     /**
      * Directories file operations may read but never write, besides the workspace and the claim's `tmp/` (where a bash
-     * command's spilled output lives and which the bash tool names to the model). For an app's own skills or reference
-     * material.
+     * command's spilled output lives and which the bash tool names to the model; a directory `createTempDir` returned is
+     * writable too, for the tool it was handed to). For an app's own skills or reference material.
      */
     readonly readRoots?: readonly string[];
     /**
@@ -72,7 +78,8 @@ export declare class EnvError extends PdaError {
  * resumed run on another host has the same identity. Temporary files and directories (a bash command's spilled
  * `pi-output-*.log` among them) live under `<root>/tmp/`, inside the claim and outside `work/`, so a path a result
  * names still exists after a takeover on another host. Commands run under no_new_privs unless `noNewPrivs` is false, and
- * every file operation is confined to the workspace (reads also to `tmp/` and `readRoots`) unless `confineFiles` is false.
+ * every file operation is confined to the workspace (reads also to `tmp/` and `readRoots`, writes also inside a directory
+ * `createTempDir` returned) unless `confineFiles` is false.
  */
 export interface ArchilEnvFactory {
     /** Rooted at the claim's `work/`; an agent `cwd` is resolved against it. */
@@ -93,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;
@@ -101,23 +108,7 @@ export declare function replaySafe<T extends ToolRegistration>(tool: T): T;
 export declare function markReadOnlySafe<T extends ToolRegistration>(tools: readonly T[], readOnly?: ReadonlySet<string>): T[];
 /**
  * pi's `CodingTools` with `read` declared replay-safe. It keeps pi's extension name, so installing it replaces
- * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.0.4 ships no ls, find or
+ * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.1.0 ships no ls, find or
  * 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,17 +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, realpath, stat } from "node:fs/promises";
-import { delimiter, dirname, join, resolve } from "node:path";
+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 { canonicalizeSync, Confinement, fileError, inside } from "./confine.js";
+import { COMMANDS_MARK, CommandRecorder } from "./commands.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`
@@ -50,17 +51,22 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
             return err(new EnvClosedError());
         this.#active++;
         this.#scope.running.add(this);
+        this.#scope.recorder?.started();
         try {
-            const confined = await this.#confine(command, options, context);
+            // A recorded environment marks its commands, so its recorder knows them from any other child of this process.
+            const recorder = this.#scope.recorder;
+            const run = recorder === undefined ? options : { ...options, env: { ...options?.env, [COMMANDS_MARK]: recorder.token } };
+            const confined = await this.#confine(command, run, context);
             if (!confined.ok)
                 return confined;
             // Again after the confinement lookups, which await; the signal then covers pi's own pre-spawn work: pi refuses
             // before spawning once it is aborted, and kills a command that spawns after.
             if (closing.signal.aborted)
                 return err(new EnvClosedError());
-            return await super.exec(confined.value, options, withAbortSignal(closing.signal, context));
+            return await super.exec(confined.value, run, withAbortSignal(closing.signal, context));
         }
         finally {
+            this.#scope.recorder?.finished();
             if (--this.#active === 0)
                 this.#scope.running.delete(this);
         }
@@ -124,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);
@@ -144,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)
@@ -259,7 +267,15 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
     async remove(path, options, context) {
         if (this.#scope.confinement === undefined)
             return super.remove(path, options, context);
-        const removed = await this.#entry(path, context, { access: "write", follow: false, strict: true }, async (pin) => pin.restore(await super.remove(pin.entry, options, context)));
+        let gone;
+        const removed = await this.#entry(path, context, { access: "write", follow: false, strict: true }, async (pin) => {
+            const result = pin.restore(await super.remove(pin.entry, options, context));
+            if (result.ok)
+                gone = pin.canonical;
+            return result;
+        });
+        if (gone !== undefined)
+            this.#scope.confinement.forgetWrites(gone); // a temp dir it was given, removed: its grant goes with it
         // `force` ignores a missing target, a missing directory above it included.
         return !removed.ok && removed.error.code === "not_found" && options?.force === true ? ok(undefined) : removed;
     }
@@ -283,11 +299,30 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
     async createTempDir(prefix, context) {
         if (context.abortSignal?.aborted)
             return err(new FileError("aborted", "aborted"));
-        const { tempRoot } = this.#scope;
+        const { tempRoot, confinement, tempCanonical } = this.#scope;
         try {
             if ((await mkdir(tempRoot, { recursive: true, mode: 0o755 })) !== undefined)
                 await chmod(tempRoot, 0o755);
-            return ok(await mkdtemp(join(tempRoot, prefix ?? "tmp-")));
+            if (confinement === undefined || tempCanonical === undefined)
+                return ok(await mkdtemp(join(tempRoot, prefix ?? "tmp-")));
+            // The tool it is handed to may write in it (vision writes its source there); the rest of tmp/ stays read-only. It is
+            // made through a held handle of tmp/ that does not follow a link (a tmp/ a command replaced with one is refused here),
+            // and granted by name under the canonical tmp/, never resolved (a directory swapped for a link later grants nothing).
+            const held = await open(tempRoot, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            let name;
+            try {
+                // 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();
+            }
+            const dir = join(tempRoot, name);
+            await confineHooks.afterTempDir?.(dir);
+            confinement.allowWrites(join(tempCanonical, name));
+            return ok(dir);
         }
         catch (error) {
             return err(fileError(error, tempRoot));
@@ -450,17 +485,22 @@ function requireSetpriv(path) {
     }
 }
 /**
- * The roots, canonical once here: file operations may use the workspace, the claim's `tmp/` (read only) and `readRoots`.
+ * The roots, canonical once here: file operations may use the workspace, the claim's `tmp/` (read only, but for the
+ * directories `createTempDir` hands out, which are writable) and `readRoots`.
  * 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(":");
@@ -469,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),
@@ -483,6 +524,14 @@ export function archilEnv(claim, options = {}) {
         running,
         closing: new AbortController(),
         confinement,
+        tempCanonical: confinement === undefined ? undefined : join(canonicalizeSync(claim.root), TEMP_DIR),
+        // A record that cannot be written (a full disk) leaves a command the next open could miss: said once on stderr, and
+        // the recorder keeps trying; the run goes on.
+        recorder: claim.commands === undefined
+            ? undefined
+            : new CommandRecorder(claim.commands, {
+                onError: (error) => process.stderr.write(`pi-durable-disk: cannot record the run's commands in ${claim.commands}: ${String(error)}\n`),
+            }),
     };
     const workOwned = runAs ? ownedOnce(claim.work, runAs) : undefined;
     const build = (target) => {
@@ -497,12 +546,13 @@ export function archilEnv(claim, options = {}) {
     const cleanup = async (context) => {
         scope.closing.abort();
         await Promise.all([...running].map((env) => env.cleanup(context)));
+        scope.recorder?.close();
     };
     return Object.assign(build, { id, cleanup });
 }
 /** 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) {
@@ -514,55 +564,10 @@ export function markReadOnlySafe(tools, readOnly = READ_ONLY_TOOLS) {
 }
 /**
  * pi's `CodingTools` with `read` declared replay-safe. It keeps pi's extension name, so installing it replaces
- * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.0.4 ships no ls, find or
+ * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.1.0 ships no ls, find or
  * grep; an app that adds them declares them safe with `markReadOnlySafe`.
  */
 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

@@ -20,7 +20,8 @@ export declare class FencedError extends PdaError {
         code?: string;
     });
 }
-export type Holder = "claim" | "owner-lock" | "store";
+/** `commands`: processes a killed incarnation's commands left that did not die when the next open killed them. */
+export type Holder = "claim" | "owner-lock" | "store" | "commands";
 /** Someone else holds the run (see `Holder`). The process exits 76. */
 export declare class HeldError extends PdaError {
     readonly holder: Holder;

package/dist/errors.js

@@ -25,7 +25,7 @@ export class FencedError extends PdaError {
         super(options.code ?? "FENCED", message, { cause: options.cause, exitCode: EXIT_FENCED });
     }
 }
-const HELD_CODES = { claim: "CLAIM_HELD", "owner-lock": "OWNER_LOCK_HELD", store: "STORE_BUSY" };
+const HELD_CODES = { claim: "CLAIM_HELD", "owner-lock": "OWNER_LOCK_HELD", store: "STORE_BUSY", commands: "COMMANDS_ALIVE" };
 /** Someone else holds the run (see `Holder`). The process exits 76. */
 export class HeldError extends PdaError {
     holder;

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/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>;

package/dist/hosts/daytona-launch.js

@@ -13,7 +13,7 @@
 // incarnation gets the token; a restart in place reads an empty stdin and reuses its live mount, as under localHost.
 // 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";
@@ -40,15 +40,20 @@ function writeState(path, state) {
     writeFileSync(`${path}.tmp`, `${JSON.stringify(state)}\n`, { mode: 0o600 });
     renameSync(`${path}.tmp`, path);
 }
-const alive = (pid, ticks) => pid !== null && ticks !== null && procStartTicks(pid) === ticks;
-/** running while either process lives; otherwise stopped after a clean exit, failed after any other end. */
+// 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 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 };
@@ -214,8 +219,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
@@ -260,7 +269,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);