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

package/dist/errors.js

@@ -0,0 +1,55 @@
+// Typed errors and exit codes shared by every module. An instance that loses its run exits 75 (fenced) or 76 (held by
+// another); both are terminal for the host's process supervisor, which must not restart into a run it lost.
+// A module's own errors extend FencedError or HeldError (overriding `code`) so one `instanceof` or `exitCodeFor` covers
+// them all, e.g. `class StoreFencedError extends FencedError` with `{ code: "STORE_FENCED" }`.
+/** EX_TEMPFAIL: the claim was revoked or its mount failed; nothing this process writes can become durable. */
+export const EXIT_FENCED = 75;
+/**
+ * Someone else holds the run: another client's delegation, another process's owner lock, another store connection. A
+ * held delegation is live or orphaned (its client gone); the supervisor revokes orphans.
+ */
+export const EXIT_HELD = 76;
+export class PdaError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        this.code = code;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+/** The claim is lost or its mount failed. Never retried on the same handle; the process exits 75. */
+export class FencedError extends PdaError {
+    constructor(message, options = {}) {
+        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", commands: "COMMANDS_ALIVE" };
+/** Someone else holds the run (see `Holder`). The process exits 76. */
+export class HeldError extends PdaError {
+    holder;
+    constructor(holder, message, options = {}) {
+        super(options.code ?? HELD_CODES[holder], message, { cause: options.cause, exitCode: EXIT_HELD });
+        this.holder = holder;
+    }
+}
+/** Any other claim failure (bad input, a refused or unverifiable mount, a CLI or control API failure). Exit 1. */
+export class ClaimError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+export function exitCodeFor(err) {
+    return err instanceof PdaError ? err.exitCode : 1;
+}
+/**
+ * Any error writing a file the claim owns (its probe, `run.json`, `owner.lock`, the run directory itself) is a fence. A
+ * revoked mount answers such writes with EIO, EROFS, ENOENT, SQLITE_CANTOPEN or a success into its local cache,
+ * so no errno is evidence that the claim is still held. Taking the owner lock is not a write: a lock
+ * another process holds is `HeldError("owner-lock")`.
+ */
+export function ownWriteFenced(what, cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new FencedError(`writing ${what} failed, so the claim cannot be trusted: ${reason}`, { cause });
+}

package/dist/fork.d.ts

@@ -0,0 +1,41 @@
+import { type AcquireOptions, type ArchilHost, type Claim, type RunRef } from "./claim.js";
+import { PdaError } from "./errors.js";
+import { type CheckControl, type CheckOptions, type SupervisorControl } from "./supervise.js";
+export type ForkErrorCode = "INVALID_ARGUMENT" | "SOURCE_NOT_RELEASED" | "SOURCE_HELD" | "TARGET_EXISTS" | "COPY_FAILED";
+export declare class ForkError extends PdaError {
+    constructor(code: ForkErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface ForkOptions {
+    readonly control: CheckControl & Pick<SupervisorControl, "getObject" | "headObject">;
+    /** The copy's two mounts go under `<mountRoot>/.fork-<stamp>/{source,target}`. */
+    readonly mountRoot: string;
+    readonly host?: ArchilHost;
+    /** Prefix of the two short-lived token users' nicknames. Default "pda-". */
+    readonly tokenPrefix?: string;
+    readonly controlTimeoutMs?: number;
+    readonly onResource?: CheckOptions["onResource"];
+    /** Replaceable for tests: how each side is mounted (default `acquire`). */
+    readonly acquire?: (options: AcquireOptions) => Promise<Claim>;
+}
+export type ForkResult = {
+    readonly run: string;
+    readonly from: string;
+    readonly sealedSeq: number;
+    readonly sourceGeneration: number;
+    readonly files: number;
+    readonly bytes: number;
+    /** Owners are preserved only when the caller is root; otherwise every copied entry belongs to the caller. */
+    readonly owners: "preserved" | "caller";
+    readonly ms: number;
+};
+/**
+ * Fork run `ref` into run `newId`. The source must be released and sealed (run.json paused, sleeping, done
+ * or failed with a `sealedSeq`, and no delegation); `newId` must not exist. A fork owns the new run's directory only
+ * while it holds that directory's exclusive mount. A fork that fails after that empties the directory through its own
+ * mount and then removes the empty directory, so a half copy never looks like a run. One that never held it (another
+ * fork or a start mounted it first) touches nothing there; it may leave the empty directory it created. Every token
+ * and mount of its own is removed either way.
+ */
+export declare function fork(ref: RunRef, newId: string, options: ForkOptions): Promise<ForkResult>;

package/dist/fork.js

@@ -0,0 +1,181 @@
+// Fork: copy a released, sealed run into a new run directory. S3 CopyObject is not supported, so both runs
+// are mounted exclusively for the copy, which also keeps either from starting meanwhile; the mounts go under a mount
+// 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 { 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";
+import { CONTROL_TIMEOUT_MS, readRunStatus, START_MARK, withTimeouts } from "./supervise.js";
+import { OWNER_LOCK } from "./run.js";
+/** A run is released, and so can be forked, in these states once its release sealed it. */
+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"]);
+export class ForkError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+/** Copy `from` into `to` entry by entry: modes, times and symlinks kept, owners when root. */
+async function copyTree(from, to, top, asRoot, count) {
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+        if (top && SKIP.has(entry.name))
+            continue;
+        const src = join(from, entry.name);
+        const dst = join(to, entry.name);
+        const st = await lstat(src);
+        if (st.isDirectory()) {
+            await mkdir(dst, { mode: st.mode & 0o7777 });
+            await copyTree(src, dst, false, asRoot, count);
+        }
+        else if (st.isSymbolicLink()) {
+            await symlink(await readlink(src), dst);
+        }
+        else if (st.isFile()) {
+            await copyFile(src, dst);
+            count.files++;
+            count.bytes += st.size;
+        }
+        else {
+            continue;
+        }
+        if (asRoot)
+            await lchown(dst, st.uid, st.gid);
+        if (st.isSymbolicLink())
+            continue;
+        await chmod(dst, st.mode & 0o7777);
+        await utimes(dst, st.atime, st.mtime);
+    }
+}
+/** Remove every entry under `root`, keeping `root`. */
+async function emptyDir(root) {
+    for (const name of await readdir(root))
+        await rm(join(root, name), { recursive: true, force: true });
+}
+/**
+ * Fork run `ref` into run `newId`. The source must be released and sealed (run.json paused, sleeping, done
+ * or failed with a `sealedSeq`, and no delegation); `newId` must not exist. A fork owns the new run's directory only
+ * while it holds that directory's exclusive mount. A fork that fails after that empties the directory through its own
+ * mount and then removes the empty directory, so a half copy never looks like a run. One that never held it (another
+ * fork or a start mounted it first) touches nothing there; it may leave the empty directory it created. Every token
+ * and mount of its own is removed either way.
+ */
+export async function fork(ref, newId, options) {
+    const t0 = performance.now();
+    const control = withTimeouts(options.control, options.controlTimeoutMs ?? CONTROL_TIMEOUT_MS);
+    runPath(newId);
+    if (newId === ref.id)
+        throw new ForkError("INVALID_ARGUMENT", "a fork needs a new run id");
+    const before = await readRunStatus(control, ref.id);
+    const released = (r) => !!r && RELEASED.includes(r.status) && r.sealedSeq !== null;
+    if (!released(before))
+        throw new ForkError("SOURCE_NOT_RELEASED", `run ${ref.id} is not released and sealed (${before ? `${before.status}, sealedSeq ${before.sealedSeq}` : "no run.json"})`);
+    if ((await findDelegations(control, ref.id)).length > 0)
+        throw new ForkError("SOURCE_HELD", `run ${ref.id} is mounted somewhere`);
+    const target = `${runPath(newId)}/`;
+    if ((await control.headObject(target)) || (await control.listObjects(target, { recursive: true })).objects.length > 0) {
+        throw new ForkError("TARGET_EXISTS", `${target} already exists`);
+    }
+    const note = options.onResource ?? (() => { });
+    const base = join(options.mountRoot, `.fork-${Date.now().toString(36)}`);
+    const tokens = [];
+    const claims = [];
+    // Set once this fork holds the new run's directory exclusively; until then the directory may be another operation's.
+    let copy;
+    let done = false;
+    const mount = async (run, side) => {
+        const t = await mintMountToken(control, { nickname: `${options.tokenPrefix ?? "pda-"}fork-${side}-${run.id}`.slice(0, 200), ttl: "1h" });
+        tokens.push(t.identifier);
+        note("token", t.identifier, side);
+        const claim = await (options.acquire ?? acquire)({ ref: run, token: t.token, mountRoot: join(base, side), host: options.host });
+        claims.push(claim);
+        note("mount", claim.root, `${run.disk}:/${runPath(run.id)}`);
+        return claim;
+    };
+    try {
+        const source = await mount(ref, "source").catch((error) => {
+            throw error instanceof HeldError ? new ForkError("SOURCE_HELD", `run ${ref.id} was mounted while forking`, { cause: error }) : error;
+        });
+        // The mounted record is authoritative: the source cannot change while this claim holds it.
+        const record = await readRunRecord(source.root);
+        if (!released(record))
+            throw new ForkError("SOURCE_NOT_RELEASED", `run ${ref.id} changed before it was mounted (${record?.status})`);
+        const owner = await lstat(source.root);
+        await createRunDir(control, newId, { uid: owner.uid, gid: owner.gid, mode: owner.mode & 0o7777 });
+        note("subdir", target);
+        copy = await mount({ ...ref, id: newId }, "target").catch((error) => {
+            throw error instanceof HeldError ? new ForkError("TARGET_EXISTS", `${target} was mounted by another fork or start`, { cause: error }) : error;
+        });
+        const count = { files: 0, bytes: 0 };
+        const asRoot = process.getuid?.() === 0;
+        try {
+            await copyTree(source.root, copy.root, true, asRoot, count);
+        }
+        catch (error) {
+            throw new ForkError("COPY_FAILED", `copying ${runPath(ref.id)} to ${target} failed: ${error.message}`, { cause: error });
+        }
+        const now = new Date().toISOString();
+        const forked = {
+            run: newId,
+            status: "paused",
+            generation: 0,
+            sealedSeq: record.sealedSeq,
+            wakeAt: null,
+            holder: null,
+            heartbeatAt: null,
+            updatedAt: now,
+            detail: { forkedFrom: { run: ref.id, generation: record.generation, sealedSeq: record.sealedSeq } },
+        };
+        await persistRecord(copy.root, `${JSON.stringify(forked, null, 2)}\n`);
+        // Each release runs the barrier first: every copied byte is durable before the target's claim goes.
+        while (claims.length > 0) {
+            const c = claims.at(-1);
+            const r = await c.release();
+            claims.pop();
+            note("unmount", c.root, r.via);
+        }
+        done = true;
+        return {
+            run: newId,
+            from: ref.id,
+            sealedSeq: record.sealedSeq,
+            sourceGeneration: record.generation,
+            ...count,
+            owners: asRoot ? "preserved" : "caller",
+            ms: Math.round(performance.now() - t0),
+        };
+    }
+    catch (error) {
+        // Undo through this fork's own mount while it still holds it; nothing is deleted over S3, where a revoke would
+        // take another operation's claim on the same id.
+        if (copy && !copy.fenced)
+            await emptyDir(copy.root).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        for (const c of claims.reverse()) {
+            await c.release().then((r) => note("unmount", c.root, r.via), () => note("unmount", c.root, "failed"));
+        }
+        // The emptied directory's own marker. S3 refuses to delete a directory with entries and deletes nothing under a
+        // delegation, so this never removes a run another fork or start has taken since this fork released it.
+        if (copy && !done) {
+            await control.deleteObjects([target], { quiet: true }).catch(() => undefined);
+            if (!(await control.headObject(target).catch(() => true)))
+                note("subdir-deleted", target);
+        }
+        for (const t of tokens) {
+            await removeMountToken(control, t).then(() => note("token-removed", t), () => { });
+        }
+        for (const side of ["source", "target"]) {
+            for (const dir of [join(base, side, "runs"), join(base, side)])
+                await rmdir(dir).catch(() => { });
+        }
+        await rmdir(base).catch(() => { });
+    }
+}

package/dist/hosts/daytona-launch.d.ts

@@ -0,0 +1,52 @@
+export declare const LAUNCH_DIR = "/run/pda";
+export declare const LAUNCH_SCRIPT: string;
+export interface LaunchSpec {
+    /** The instance command and its arguments (absolute program path). */
+    argv: string[];
+    /** The instance's whole environment besides PATH, LANG and HOME (the holder handle, an app's settings). */
+    env: Record<string, string>;
+    /** The run user (name or uid). Required when the launcher runs as root, which never runs the instance as root. */
+    user?: string;
+    group?: string;
+    /** Restart after a non-terminal exit (default true). */
+    restart?: boolean;
+    restartDelayMs?: number;
+    /** More than `burst` restarts within `intervalMs` ends the launcher (systemd's start limit). Default 5 in 60 s. */
+    restartLimit?: {
+        burst: number;
+        intervalMs: number;
+    };
+    terminalExits?: number[];
+}
+export type LaunchPhase = "running" | "restarting" | "stopping" | "exited";
+export type LaunchState = {
+    launcher: number;
+    launcherTicks: number | null;
+    phase: LaunchPhase;
+    instance: number | null;
+    instanceTicks: number | null;
+    /** Incarnations spawned so far; 0 means the instance never ran (refused spec, failed spawn). */
+    spawned: number;
+    restarts: number;
+    /** The last incarnation's exit code (128 + signal number for a signal), null while one runs. */
+    exit: number | null;
+    signal: string | null;
+    /** Why the launcher stopped restarting: terminal exit, clean exit, stopped, restart limit, spawn failure. */
+    reason: string | null;
+    at: string;
+};
+export type LaunchStatus = {
+    status: "running" | "stopped" | "failed";
+    state: LaunchState | null;
+    launcherAlive: boolean;
+    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. */
+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>;
+/** Spawn `serve` in its own session and wait until its first incarnation is spawned (or the launcher ended without one). */
+export declare function start(dir: string, name: string, timeoutMs?: number, stage?: string): Promise<LaunchState | null>;
+/** SIGTERM the launcher (it drains the instance); past the timeout SIGKILL the instance's group and the launcher. */
+export declare function stop(dir: string, name: string, timeoutMs: number): Promise<LaunchStatus>;

package/dist/hosts/daytona-launch.js

@@ -0,0 +1,270 @@
+// The in-box launcher for `daytonaHost`: a sandbox has no systemd (the Daytona daemon is PID 1), so this keeps the instance
+// alive in place, as a systemd unit does on a host.
+// It runs as root, started through the toolbox, and keeps one instance of a run alive in its box:
+//   start <name>   move the spec and token from the toolbox user's staging directory (`--stage`), spawn `serve` detached (its own session, so the toolbox's process-group kill never reaches it), wait
+//                  until the first incarnation is spawned, print the state
+//   serve <name>   read the spec and the mount token, unlink the token file, run the instance as the run user with the
+//                  token on a pipe to its stdin, restart it after a non-terminal exit (never after 0, 65, 70, 75 or 76,
+//                  and not past the restart limit), forward SIGTERM to it, write `<name>.state` on every change
+//   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.
+// 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 { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { procStartTicks, TERMINAL_EXITS } from "./local-host.js";
+export const LAUNCH_DIR = "/run/pda";
+export const LAUNCH_SCRIPT = fileURLToPath(import.meta.url);
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const SAFE_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+const files = (dir, name) => {
+    if (!NAME.test(name))
+        throw new Error(`launch name ${JSON.stringify(name)} is not one safe path segment`);
+    const base = join(dir, name);
+    return { spec: `${base}.json`, token: `${base}.token`, state: `${base}.state`, log: `${base}.log` };
+};
+export function readState(dir, name) {
+    const path = files(dir, name).state;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeState(path, state) {
+    writeFileSync(`${path}.tmp`, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+}
+// 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. */
+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)
+        return { status: "running", state, launcherAlive, instanceAlive };
+    const clean = state.phase === "exited" && state.exit === 0;
+    return { status: clean ? "stopped" : "failed", state, launcherAlive, instanceAlive };
+}
+/** /etc/passwd or /etc/group field lookup: a name or a numeric id to the numeric id (and the passwd home). */
+function lookup(file, key) {
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const f = line.split(":");
+        if (f.length >= 3 && (f[0] === key || f[2] === key))
+            return { id: Number(f[2]), home: file === "/etc/passwd" ? f[5] : undefined };
+    }
+    throw new Error(`${key} is not in ${file}`);
+}
+const SIGNALS = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
+/** Who the instance runs as: the spec's user (numeric ids for spawn) or, with no user, this process. */
+function runAs(spec) {
+    const isRoot = process.getuid?.() === 0;
+    if (spec.user === undefined) {
+        if (isRoot)
+            throw new Error("the launcher runs as root and the spec names no run user");
+        return { home: process.env.HOME ?? "/" };
+    }
+    const u = lookup("/etc/passwd", spec.user);
+    const gid = lookup("/etc/group", spec.group ?? spec.user).id;
+    if (u.id === 0)
+        throw new Error("the instance never runs as root");
+    if (isRoot)
+        return { uid: u.id, gid, home: u.home ?? "/" };
+    if (u.id !== process.getuid?.())
+        throw new Error("switching to the run user needs root");
+    return { home: u.home ?? "/" };
+}
+/** The loop `serve` runs; resolves with the final state. */
+export async function serve(dir, name) {
+    const f = files(dir, name);
+    const state = { launcher: process.pid, launcherTicks: procStartTicks(process.pid), phase: "running", instance: null, instanceTicks: null, spawned: 0, restarts: 0, exit: null, signal: null, reason: null, at: new Date().toISOString() };
+    const save = (patch) => writeState(f.state, Object.assign(state, patch, { at: new Date().toISOString() }));
+    let spec;
+    let token;
+    let ids;
+    try {
+        spec = JSON.parse(readFileSync(f.spec, "utf8"));
+        // No token file: a launcher started again after a crash runs its instance with an empty stdin.
+        token = existsSync(f.token) ? readFileSync(f.token, "utf8").trim() : "";
+        if (existsSync(f.token))
+            unlinkSync(f.token);
+        ids = runAs(spec);
+    }
+    catch (err) {
+        save({ phase: "exited", exit: 1, reason: `refused: ${err.message}` });
+        return state;
+    }
+    const restart = spec.restart !== false;
+    const delay = spec.restartDelayMs ?? 1_000;
+    const limit = spec.restartLimit ?? { burst: 5, intervalMs: 60_000 };
+    const terminal = spec.terminalExits ?? [...TERMINAL_EXITS];
+    let stopping = false;
+    let child = null;
+    const onSignal = () => {
+        stopping = true;
+        if (state.phase === "restarting")
+            save({ phase: "stopping" });
+        else if (child?.exitCode === null) {
+            save({ phase: "stopping" });
+            child.kill("SIGTERM");
+        }
+    };
+    process.on("SIGTERM", onSignal);
+    process.on("SIGINT", onSignal);
+    const log = openSync(f.log, "a", 0o600);
+    const recent = [];
+    try {
+        for (;;) {
+            const env = { PATH: SAFE_PATH, LANG: "C.UTF-8", HOME: ids.home, ...spec.env };
+            const first = token !== null;
+            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 });
+                await new Promise((resolve, reject) => {
+                    child.once("spawn", resolve);
+                    child.once("error", reject);
+                });
+            }
+            catch (err) {
+                save({ phase: "exited", instance: null, instanceTicks: null, exit: 1, reason: `spawn failed: ${err.message}` });
+                return state;
+            }
+            if (first) {
+                child.stdin.on("error", () => { });
+                child.stdin.end(token ? `${token}\n` : "");
+                token = null;
+            }
+            save({ phase: stopping ? "stopping" : "running", instance: child.pid, instanceTicks: procStartTicks(child.pid), spawned: state.spawned + 1, exit: null, signal: null });
+            if (stopping)
+                child.kill("SIGTERM");
+            const [code, signal] = await new Promise((resolve) => child.once("exit", (c, s) => resolve([c, s])));
+            const exit = code ?? 128 + (SIGNALS[signal ?? ""] ?? 0);
+            save({ instance: null, instanceTicks: null, exit, signal });
+            const now = Date.now();
+            recent.push(now);
+            while (recent.length && recent[0] < now - limit.intervalMs)
+                recent.shift();
+            const end = stopping ? "stopped"
+                : exit === 0 ? "clean exit"
+                    : terminal.includes(exit) ? `terminal exit ${exit}`
+                        : !restart ? "restart disabled"
+                            : recent.length > limit.burst ? `restart limit (${limit.burst} in ${limit.intervalMs} ms)`
+                                : null;
+            if (end) {
+                save({ phase: "exited", reason: end });
+                return state;
+            }
+            save({ phase: "restarting", restarts: state.restarts + 1 });
+            await new Promise((r) => setTimeout(r, delay));
+            if (stopping) {
+                save({ phase: "exited", reason: "stopped" });
+                return state;
+            }
+        }
+    }
+    finally {
+        closeSync(log);
+        process.off("SIGTERM", onSignal);
+        process.off("SIGINT", onSignal);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Spawn `serve` in its own session and wait until its first incarnation is spawned (or the launcher ended without one). */
+export async function start(dir, name, timeoutMs = 30_000, stage) {
+    const f = files(dir, name);
+    if (readState(dir, name))
+        throw new Error(`${name} was already launched in this box`);
+    if (stage) {
+        // The toolbox's user uploaded into its own 0700 staging directory; move both files into the root-only directory.
+        const from = files(stage, name);
+        for (const [src, dst] of [[from.spec, f.spec], [from.token, f.token]]) {
+            if (!existsSync(src))
+                continue;
+            writeFileSync(dst, readFileSync(src), { mode: 0o600 });
+            unlinkSync(src);
+        }
+    }
+    if (!existsSync(f.spec))
+        throw new Error(`no launch spec at ${f.spec}`);
+    const child = spawn(process.execPath, [LAUNCH_SCRIPT, "serve", name, "--dir", dir], { detached: true, stdio: "ignore", env: { PATH: SAFE_PATH, LANG: "C.UTF-8" } });
+    child.unref();
+    for (const t0 = Date.now(); Date.now() - t0 < timeoutMs; await sleep(25)) {
+        const s = readState(dir, name);
+        if (s && (s.phase === "exited" || s.spawned > 0))
+            return s;
+    }
+    return readState(dir, name);
+}
+/** SIGTERM the launcher (it drains the instance); past the timeout SIGKILL the instance's group and the launcher. */
+export async function stop(dir, name, timeoutMs) {
+    const kill = (pid, ticks, signal, group = false) => {
+        if (!alive(pid, ticks))
+            return;
+        try {
+            process.kill(group ? -pid : pid, signal);
+        }
+        catch {
+            // gone between the check and the signal
+        }
+    };
+    let s = launchStatus(dir, name);
+    if (s.status !== "running")
+        return s;
+    if (s.launcherAlive)
+        kill(s.state.launcher, s.state.launcherTicks, "SIGTERM");
+    else
+        kill(s.state.instance, s.state.instanceTicks, "SIGTERM");
+    for (const t0 = Date.now(); Date.now() - t0 < timeoutMs; await sleep(50)) {
+        s = launchStatus(dir, name);
+        if (s.status !== "running")
+            return s;
+    }
+    kill(s.state.instance, s.state.instanceTicks, "SIGKILL", true);
+    kill(s.state.launcher, s.state.launcherTicks, "SIGKILL");
+    for (let i = 0; i < 40 && launchStatus(dir, name).status === "running"; i++)
+        await sleep(50);
+    return launchStatus(dir, name);
+}
+async function main(argv) {
+    const [verb, name, ...rest] = argv;
+    const opt = (flag) => {
+        const i = rest.indexOf(flag);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    const dir = opt("--dir") ?? LAUNCH_DIR;
+    const timeoutMs = Number(opt("--timeout-ms") ?? 30_000);
+    const print = (v) => process.stdout.write(`${JSON.stringify(v)}\n`);
+    switch (verb) {
+        case "serve":
+            await serve(dir, name);
+            return 0;
+        case "start": {
+            const s = await start(dir, name, timeoutMs, opt("--stage"));
+            print(s);
+            return s && s.spawned > 0 ? 0 : 1;
+        }
+        case "status":
+            print(launchStatus(dir, name));
+            return 0;
+        case "stop":
+            print(await stop(dir, name, timeoutMs));
+            return 0;
+        default:
+            process.stderr.write("usage: daytona-launch.ts start|serve|status|stop NAME [--dir DIR] [--stage DIR] [--timeout-ms MS]\n");
+            return 2;
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === LAUNCH_SCRIPT) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(1);
+    });
+}