@parcha/pi-durable-disk 0.1.0-beta.21 → 0.1.0-beta.26

package/dist/hosts/local-host.js

@@ -14,7 +14,7 @@
 import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
-import { extname, join } from "node:path";
+import { basename, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ARCHIL_SCOPED, DEAD_CONNECTION, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
 import { EXIT_DATAERR, EXIT_FENCED, EXIT_HELD, EXIT_SOFTWARE, PdaError } from "../errors.js";
@@ -73,6 +73,14 @@ export function currentBootId() {
         throw new Error("this machine's boot id cannot be read");
     return boot;
 }
+/** The uid a user number or name stands for (a name through /etc/passwd), or undefined when nothing names it. */
+async function uidOf(user) {
+    if (/^\d+$/.test(user))
+        return Number(user);
+    const rows = await readFile("/etc/passwd", "utf8").then((text) => text.split("\n").map((line) => line.split(":")), () => []);
+    const row = rows.find((fields) => fields.length >= 3 && fields[0] === user);
+    return row ? Number(row[2]) : undefined;
+}
 const firstLine = (r) => (r.stderr.trim().split("\n").at(-1) ?? "").slice(0, 300);
 const okRan = (r) => r.code === 0 && !r.timedOut;
 /** `systemctl show` output as a map. */
@@ -104,6 +112,35 @@ export function unitStatus(show) {
             return "unknown";
     }
 }
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The text of an `EnvironmentFile=`: one `NAME="value"` line each, with `\` and `"` escaped inside the double quotes (nothing
+ * else is special there: systemd expands no `$` in this file). A name that is not a variable name, or a value with a newline,
+ * a carriage return or a NUL, cannot be written faithfully, so it is refused rather than mangled.
+ */
+/**
+ * The unit's own `ExecStopPost=` (`+`: as root, whatever `User=` is) that removes its environment file when the unit ends for
+ * good, so an instance that parks or finishes on its own leaves nothing behind. A restart in place loads the file again, so it
+ * stays after any exit systemd will restart: with `Restart=on-failure`, one that is not `success` and not in `TERMINAL_EXITS`.
+ * (`$$` is systemd's escape for `$`; it hands the script `SERVICE_RESULT` and `EXIT_STATUS`.)
+ */
+function environmentCleanup(path, restarts) {
+    if (!restarts)
+        return `+/bin/rm -f ${path}`;
+    const final = ["success:*", ...TERMINAL_EXITS.map((code) => `exit-code:${code}`)].join("|");
+    return `+/bin/sh -c 'case "$$SERVICE_RESULT:$$EXIT_STATUS" in ${final}) /bin/rm -f "$$1";; esac' sh ${path}`;
+}
+function environmentFile(env) {
+    const lines = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (!ENV_NAME.test(name))
+            throw new LocalHostError("INVALID_ARGUMENT", `${JSON.stringify(name)} is not an environment variable name`);
+        if (typeof value !== "string" || /[\r\n\0]/.test(value))
+            throw new LocalHostError("INVALID_ARGUMENT", `the value of ${name} is not a string without a newline, a carriage return or a NUL`);
+        lines.push(`${name}="${value.replace(/[\\"]/g, "\\$&")}"`);
+    }
+    return `${lines.join("\n")}\n`;
+}
 export function localHost(opts = {}) {
     const mode = opts.mode ?? "systemd";
     const mountRoot = opts.mountRoot ?? DEFAULT_MOUNT_ROOT;
@@ -126,6 +163,28 @@ export function localHost(opts = {}) {
     const procMounts = opts.procMounts ?? "/proc/self/mounts";
     const mine = (h) => h.driver === "local" && h.host === hostName;
     const mountpointOf = (ref) => join(mountRoot, runPath(ref.id));
+    const runMountpoint = (mp) => {
+        try {
+            return mp === join(mountRoot, runPath(basename(mp)));
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * The unit of a systemd handle this driver could have made: a safe name with its prefix, whose mountpoint is one run's
+     * under its mount root; undefined for any other. A handle comes back from run.json, which the run's user can write, and
+     * stop and kill act on it as root (systemctl, unmount, rmdir), as the docker and daytona drivers act only on their fleet's.
+     * They refuse any other with the reason, so a supervisor's log never reports a stop that did not happen.
+     */
+    const ownUnit = (h) => {
+        const { unit, mountpoint } = h;
+        if (typeof unit !== "string" || !UNIT_SAFE.test(unit) || !unit.startsWith(prefix))
+            return undefined;
+        return typeof mountpoint === "string" && runMountpoint(mountpoint) ? unit : undefined;
+    };
+    const notOwnUnit = (h, what) => new LocalHostError("INVALID_ARGUMENT", `the handle's unit ${JSON.stringify(h.unit)} at ${JSON.stringify(h.mountpoint)} is not one this driver starts (${prefix}<run id>-<stamp>, a run's mountpoint under ${mountRoot}): nothing ${what}`);
+    const notOwnPid = (h, what) => new LocalHostError("INVALID_ARGUMENT", `the handle names pid ${JSON.stringify(h.pid)} with start ticks ${JSON.stringify(h.startTicks)}, not a process this driver started: nothing ${what}`);
     const mounted = async (mp) => (await readFile(procMounts, "utf8")).split("\n").some((l) => l.split(" ")[1] === mp);
     const parkMs = opts.parkThresholdMs === undefined ? LOCAL_PARK_THRESHOLD_MS : opts.parkThresholdMs;
     const drainMs = Math.max(0, stopTimeoutMs - Math.min(5_000, stopTimeoutMs / 2));
@@ -137,15 +196,18 @@ export function localHost(opts = {}) {
     ];
     const holderEnv = (h) => JSON.stringify(h);
     const tokenFile = (unit) => join(TOKEN_DIR, `${unit}.mount-token`);
-    async function writeTokenFile(path, token) {
+    /** The unit's environment, loaded with `EnvironmentFile=`: a value on `systemd-run`'s argv is logged by sudo and shown by `systemctl show`. */
+    const envFile = (unit) => join(TOKEN_DIR, `${unit}.env`);
+    /** Writes a root-only (0600) file under the token directory; `content` goes through stdin, never an argument. */
+    async function writeSecretFile(path, content, what) {
         if (!sudo) {
             await mkdir(TOKEN_DIR, { recursive: true, mode: 0o700 });
-            await writeFile(path, token, { mode: 0o600 });
+            await writeFile(path, content, { mode: 0o600 });
             return;
         }
-        const r = await root(["/bin/sh", "-c", 'umask 077 && mkdir -p "$1" && cat > "$2"', "sh", TOKEN_DIR, path], { input: token });
+        const r = await root(["/bin/sh", "-c", 'umask 077 && mkdir -p "$1" && cat > "$2"', "sh", TOKEN_DIR, path], { input: content });
         if (!okRan(r))
-            throw new LocalHostError("START_FAILED", `cannot write the mount token file: ${firstLine(r)}`);
+            throw new LocalHostError("START_FAILED", `cannot write the ${what}: ${firstLine(r)}`);
     }
     /** Replace the token file by an empty one: the started instance's open fd keeps the token, the path no longer has it. */
     async function emptyTokenFile(path) {
@@ -165,10 +227,13 @@ export function localHost(opts = {}) {
         const mountpoint = mountpointOf(ref);
         const handle = { driver: "local", mode: "systemd", host: hostName, bootId, unit, mountpoint };
         const env = { ...opts.env, ...extra, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
+        const environment = environmentFile(env);
         const path = tokenFile(unit);
-        await writeTokenFile(path, token);
+        const envPath = envFile(unit);
+        await writeSecretFile(path, token, "mount token file");
         let started = false;
         try {
+            await writeSecretFile(envPath, environment, "environment file");
             const argv = [
                 SYSTEMD_RUN,
                 `--unit=${unit}`,
@@ -181,7 +246,8 @@ export function localHost(opts = {}) {
                 "-p", `User=${user}`,
                 "-p", `Group=${group}`,
                 "-p", `StandardInput=file:${path}`,
-                ...Object.entries(env).map(([k, v]) => `--setenv=${k}=${v}`),
+                "-p", `EnvironmentFile=${envPath}`,
+                "-p", `ExecStopPost=${environmentCleanup(envPath, opts.restart !== false)}`,
                 "--",
                 ...command,
                 ...runFlags(ref),
@@ -195,8 +261,13 @@ export function localHost(opts = {}) {
         }
         finally {
             // Type=exec: systemd-run returns after the exec, so the instance's stdin is already open on the token. The path
-            // stays (empty) because a restart in place opens it again; stop removes it.
-            await (started ? emptyTokenFile(path) : removeFile(path)).catch(() => { });
+            // stays (empty) because a restart in place opens it again; stop removes it. The environment file stays whole: a
+            // restart in place loads it again, and stop removes it. The unit's ExecStopPost removes the file when
+            // it ends for good (a park, a finish, a terminal exit). A start that failed leaves neither.
+            if (started)
+                await emptyTokenFile(path).catch(() => { });
+            else
+                await Promise.all([removeFile(path), removeFile(envPath)]).catch(() => { });
         }
     }
     async function startChild(ref, token, extra) {
@@ -286,8 +357,25 @@ export function localHost(opts = {}) {
         hostName,
         mountRoot,
         kills: "process",
+        instanceOf: (h) => {
+            if (h.driver !== "local" || typeof h.host !== "string")
+                return undefined;
+            const which = h.mode === "systemd" && typeof h.unit === "string" ? `unit\0${h.unit}` : h.mode === "child" && typeof h.tag === "string" ? `tag\0${h.tag}` : undefined;
+            return which === undefined ? undefined : `local\0${h.host}\0${String(h.bootId)}\0${which}`;
+        },
         async start(ref, token, attempt) {
             runPath(ref.id);
+            // Never as root: the instance and the agent's tools would share a uid with the archil daemon that holds the mount
+            // token, and own run.json and the store outright.
+            if (mode === "systemd" && user.trim() === "") {
+                throw new LocalHostError("INVALID_ARGUMENT", "the user is empty, and systemd runs a unit with an empty User= as root: name the unprivileged user the instance runs as (user)");
+            }
+            if (mode === "systemd" && (await uidOf(user)) === 0) {
+                throw new LocalHostError("INVALID_ARGUMENT", `user ${user} is root: name the unprivileged user the instance runs as (user)`);
+            }
+            if (mode === "child" && process.getuid?.() === 0) {
+                throw new LocalHostError("INVALID_ARGUMENT", "child mode runs the instance as this process's user, which is root: use systemd mode with a user");
+            }
             const extra = attemptEnv(attempt, (m) => new LocalHostError("INVALID_ARGUMENT", m));
             return mode === "systemd" ? startUnit(ref, token, extra) : startChild(ref, token, extra);
         },
@@ -313,7 +401,7 @@ export function localHost(opts = {}) {
                 // real process, then. A pid of 1 or below names a group (`kill(-0)` is this supervisor's own, `kill(-1)` every
                 // process it may signal), and without start ticks nothing tells a reused pid from the instance.
                 if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
-                    return;
+                    throw notOwnPid(h, "stopped");
                 const alive = () => procStartTicks(pid) === h.startTicks;
                 if (!alive())
                     return;
@@ -329,22 +417,24 @@ export function localHost(opts = {}) {
                     process.kill(-pid, "SIGKILL");
                 return;
             }
-            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
-                return;
-            const stopUnit = () => root([SYSTEMCTL, "stop", `${h.unit}.service`], { timeoutMs: stopTimeoutMs + 10_000 });
+            const unit = ownUnit(h);
+            if (unit === undefined)
+                throw notOwnUnit(h, "stopped");
+            const stopUnit = () => root([SYSTEMCTL, "stop", `${unit}.service`], { timeoutMs: stopTimeoutMs + 10_000 });
             let r = await stopUnit();
-            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+            if (!okRan(r) && unitStatus(await show(unit)) === "running") {
                 // A unit that outlives SIGKILL is wedged in its mount (a FUSE request its daemon never answers): kill the
                 // daemon so those requests fail and the processes can die, then stop once more.
-                await killDaemons(h.unit);
+                await killDaemons(unit);
                 r = await stopUnit();
-                if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
-                    throw new LocalHostError("STOP_FAILED", `systemctl stop ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+                if (!okRan(r) && unitStatus(await show(unit)) === "running") {
+                    throw new LocalHostError("STOP_FAILED", `systemctl stop ${unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
                 }
             }
-            await cleanMount(h.unit, String(h.mountpoint));
-            await root([SYSTEMCTL, "reset-failed", `${h.unit}.service`]);
-            await removeFile(tokenFile(h.unit));
+            await cleanMount(unit, String(h.mountpoint));
+            await root([SYSTEMCTL, "reset-failed", `${unit}.service`]);
+            await removeFile(tokenFile(unit));
+            await removeFile(envFile(unit));
         },
         async kill(h) {
             if (!mine(h) || h.bootId !== bootId)
@@ -352,7 +442,9 @@ export function localHost(opts = {}) {
             if (h.mode === "child") {
                 const pid = Number(h.pid);
                 // As in stop: only a real process, and only the one the handle names (its start ticks).
-                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number" || procStartTicks(pid) !== h.startTicks)
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
+                    throw notOwnPid(h, "killed");
+                if (procStartTicks(pid) !== h.startTicks)
                     return;
                 try {
                     process.kill(-pid, "SIGKILL");
@@ -362,13 +454,14 @@ export function localHost(opts = {}) {
                 }
                 return;
             }
-            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
-                return;
+            const unit = ownUnit(h);
+            if (unit === undefined)
+                throw notOwnUnit(h, "killed");
             // Every process of the unit's control group at once, the instance's commands included. Its FUSE daemon runs in a
             // scope of its own and keeps the mount, as after an OOM kill; the unit restarts in place unless restart is off.
-            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${h.unit}.service`]);
-            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
-                throw new LocalHostError("KILL_FAILED", `systemctl kill ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${unit}.service`]);
+            if (!okRan(r) && unitStatus(await show(unit)) === "running") {
+                throw new LocalHostError("KILL_FAILED", `systemctl kill ${unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
             }
         },
     };

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
 export type { AcquireOptions, ArchilHost, Claim, ControlApi, PathlessResolver, RunRef, Unmounted } from "./claim.js";
 export { readReleased, withClaim } from "./with-claim.js";
 export type { ClaimControl, HeldPath, WithClaimOptions } from "./with-claim.js";
+export { listRunFiles, readRunFile, RunFileError } from "./run-files.js";
+export type { RunFileControl, RunFileErrorCode } from "./run-files.js";
 export { PathOutsideWorkError } from "./confine.js";
 export type { RefusalReason } from "./confine.js";
 export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
@@ -28,7 +30,7 @@ export type { CreateSandboxBody, DaytonaClient, DaytonaHostErrorCode, DaytonaHos
 export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
 export type { RequestOptions, RunResponse, RunServer, ServeConfigErrorCode, ServeErrorCode, ServeOptions } from "./serve.js";
 export { archilPlace, localPlace, PlaceError } from "./place.js";
-export type { ArchilPlaceOptions, LocalPlaceOptions, Place, PlaceContext, PlaceErrorCode, PlaceExit, PlaceKill, PlaceOutcome, PlacePaths, PlaceRecordHome, PlaceRecovery, PlaceRunner, PlaceSignal, PlaceStatus, RecordControl, RunnerOrder } from "./place.js";
+export type { ArchilPlaceOptions, LocalPlaceOptions, Place, PlaceContext, PlaceErrorCode, PlaceExit, PlaceKill, PlaceOutcome, PlacePaths, PlaceRecordHome, PlaceRecovery, PlaceRunner, PlaceSignal, PlaceStatus, RecordControl, RunnerOrder, UnheldHook, UnheldRun, UnheldStart } from "./place.js";
 export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
 export type { BusyState, DrainOptions, Parking, ParkOptions, ParkResult, ParkTarget } from "./park.js";
 export { fork, ForkError, forkLocal } from "./fork.js";

package/dist/index.js

@@ -9,6 +9,8 @@ export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySaf
 export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
 // A short exclusive claim on any path of a disk, and a consistent S3 read of a released file (an agent home beside the runs).
 export { readReleased, withClaim } from "./with-claim.js";
+// A run's own files, read over the control: never a mount, a write, or a wait on the claim.
+export { listRunFiles, readRunFile, RunFileError } from "./run-files.js";
 export { PathOutsideWorkError } from "./confine.js";
 export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
 // The app contract: what `--app` names.

package/dist/place.d.ts

@@ -148,8 +148,16 @@ export interface Place {
     release(): Promise<void>;
     /** A place whose runners record where the supervisor cannot read says where, and brings the recording home. */
     readonly recordHome?: PlaceRecordHome;
+    /**
+     * The bytes of the run's own file `path` (`runs/<id>/<path>`), or null when there is no such file; every other failure
+     * throws a `RunFileError` (INVALID_PATH, RUN_MISSING, NOT_A_FILE, CONTROL_API_FAILED). Read only: never a write, never
+     * the claim. A place never parses what it reads.
+     */
+    readRunFile?(path: string): Promise<Uint8Array | null>;
+    /** The names directly under `dir` in the run (`""` for its root), sorted; [] for a directory not there yet. A missing run, or a failed read, throws. */
+    listRunFiles?(dir: string): Promise<string[]>;
 }
-export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED" | "BOX_GONE" | "CARRY_FAILED" | "BLOB_MISMATCH" | "DIRS_REFUSED";
+export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED" | "BOX_GONE" | "CARRY_FAILED" | "BLOB_MISMATCH" | "DIRS_REFUSED" | "WINDOW_CLOSED" | "CONTROL_API_FAILED" | "UNHELD_FAILED";
 export declare class PlaceError extends PdaError {
     constructor(code: PlaceErrorCode, message: string, options?: {
         cause?: unknown;
@@ -203,7 +211,62 @@ export interface ArchilPlaceOptions {
      * `signals-failed` and ends. Default 60 s.
      */
     signalFailMs?: number;
+    /**
+     * A hook in each start's window while nobody holds the run: after ensureRunning's revoke and start mark and after the
+     * run's directories are made, before the driver starts anything. It runs once per start, a takeover's included, and
+     * what it returns is added to that start's environment. Needs `ensure.create` (what it puts is the run user's) and a
+     * control that lists. See `UnheldHook`.
+     */
+    unheld?: UnheldHook;
+    /** How long `unheld` may take. Default 30 s; past it the hook's signal aborts and the start fails (UNHELD_FAILED). */
+    unheldTimeoutMs?: number;
 }
+/**
+ * The run's own files during a start's window (`runs/<id>/` only, K8's path rules): nobody holds the run, so the place
+ * is the only writer for this start. Two supervisors can still be in one window at once (the mount, not the window,
+ * admits one of their instances), so a put is not exclusive between them.
+ */
+export interface UnheldRun {
+    readonly id: string;
+    /** Aborted at the hook's bound (`unheldTimeoutMs`). */
+    readonly signal: AbortSignal;
+    /** The file's bytes, or null when there is no such file yet (`readRunFile`). */
+    read(path: string): Promise<Uint8Array | null>;
+    /** The names directly under `dir` ("" for the run's root), sorted; [] for a directory not made yet (`listRunFiles`). */
+    list(dir: string): Promise<string[]>;
+    /**
+     * Create `path` holding `text`, owned by the run user, mode 0644, making each missing parent first (the run user's,
+     * 0755). A path already there is EXISTS, and nothing is written. For non-secret run files (labels): a secret never
+     * goes through put, since a put file is readable in the run. A put the server refuses because a delegation holds the
+     * run (409 OperationAborted), and any put after the hook returned or overran, is WINDOW_CLOSED; any other failure is
+     * CONTROL_API_FAILED (`RunFileError`). A put the hook starts and does not await still settles inside the window: the
+     * driver starts only once every put has settled, within the hook's bound.
+     */
+    put(path: string, text: string): Promise<void>;
+}
+/** Which start the window is for: the generation it opens, and the host box it will make when the place hands labels over. */
+export type UnheldStart = {
+    readonly attempt: number;
+    /** Exactly the HOST_BOX this start carries; absent when the place hands no label over. */
+    readonly box?: {
+        readonly provider: string;
+        readonly key: string;
+        readonly run: string;
+    };
+};
+/**
+ * A hook in a start's window (`ArchilPlaceOptions.unheld`). What it returns is added to that start's environment, which
+ * the instance can read: plain values only. A name the start already sets (PATH, PDA_HOLDER, HOST_BOX or one in the
+ * order's environment), a name that is not a variable name, a key-shaped name (a KEY, TOKEN, SECRET, PASSWORD, PASSWD,
+ * CREDENTIAL or CREDENTIALS segment) or a value that is not a string without NUL fails the start (INVALID_ARGUMENT,
+ * naming the variable, never its value).
+ *
+ * A start fails, and the driver never starts a box, when any put in the hook was refused because the run is held
+ * (WINDOW_CLOSED, even if the hook caught it), when the hook throws a CONTROL_API_FAILED of the control
+ * (CONTROL_API_FAILED), or when it throws anything else or overruns its bound (UNHELD_FAILED). The start's caller sees
+ * the driver's start failure from ensureRunning (HOST_START_FAILED), with that PlaceError as its cause.
+ */
+export type UnheldHook = (run: UnheldRun, start: UnheldStart) => Promise<Readonly<Record<string, string>> | void>;
 /** The listing `recordHome` reads the run's recordings with: S3 ListObjects, each object's size when the API gives it. */
 export interface RecordControl {
     listObjects(prefix: string, options?: {

package/dist/place.js

@@ -13,6 +13,8 @@ import { DEFAULT_MOUNT_ROOT, findDelegations, mintMountToken, pathlessResolver,
 import { reapCommands } from "./commands.js";
 import { HeldError, PdaError } from "./errors.js";
 import { takeOwnerLock } from "./run.js";
+import { listLocalRunFiles, listRunFiles, putRunFile, readLocalRunFile, readRunFile, RunFileError } from "./run-files.js";
+import { ENV_NAME, keyShaped } from "./hosts/attempt-env.js";
 import { readRunRecord } from "./status.js";
 import { CONTROL_TIMEOUT_MS, ensureRunning, readRunStatus, readStartMark, TOKEN_TTL, withTimeouts, } from "./supervise.js";
 export class PlaceError extends PdaError {
@@ -173,6 +175,8 @@ export function localPlace(options) {
         return {
             name: "local",
             paths,
+            readRunFile: (path) => readLocalRunFile(root, paths.id, path),
+            listRunFiles: (dir) => listLocalRunFiles(root, paths.id, dir),
             kills: ctx.destroyBoxes ? ["process", "box"] : ["process"],
             start,
             // The runner is a child of this machine, so its kill request is the supervisor's own file.
@@ -589,6 +593,17 @@ const requestName = (attempt) => `kill-${countFrom1(attempt)}.json`;
  */
 export function archilPlace(options) {
     const { host } = options;
+    const unheldMs = options.unheldTimeoutMs ?? 30_000;
+    if (options.unheld !== undefined) {
+        if (typeof options.unheld !== "function")
+            throw new PlaceError("INVALID_ARGUMENT", "unheld is not a function");
+        if (!options.ensure?.create)
+            throw new PlaceError("INVALID_ARGUMENT", "unheld needs ensure.create: what its hook puts is the run user's, or the run's process could not rely on it");
+        if (typeof options.control.listObjects !== "function")
+            throw new PlaceError("INVALID_ARGUMENT", "unheld needs a control that can list (listObjects): its hook's read and list use it");
+        if (!(Number.isFinite(unheldMs) && unheldMs > 0))
+            throw new PlaceError("INVALID_ARGUMENT", "unheldTimeoutMs is not a positive number of milliseconds");
+    }
     // Every call the place makes on the disk is bounded as ensureRunning bounds its own: one that does not answer fails as
     // CONTROL_API_FAILED, so a stalled request never leaves a recovery, a release or a runner's end waiting forever.
     const control = withTimeouts(options.control, options.ensure?.controlTimeoutMs ?? CONTROL_TIMEOUT_MS);
@@ -611,6 +626,12 @@ export function archilPlace(options) {
         let resolver = pathlessResolver(control);
         const records = `${runPath(ref.id)}/${RECORDS}/`;
         const recording = typeof options.control.listObjects === "function";
+        /**
+         * Whether each host box's runner is told its label (HOST_BOX): the driver makes boxes and names their provider, and this
+         * place can read the label back (its read members need a control that lists). A label it could never read is never
+         * handed over.
+         */
+        const handingOver = recording && typeof host.box === "function" && typeof host.provider === "string" && host.provider !== "";
         const owner = options.ensure?.create;
         /**
          * Before attempt `gen`'s runner starts: the EMPTY directories it writes into, `signals/` and, with `recordHome`,
@@ -637,6 +658,88 @@ export function archilPlace(options) {
                 }
             }
         };
+        /**
+         * The hook's turn in a start's window: its run members, its bound, then what it returned, checked. Fails closed: a put
+         * refused because the run is held fails the start even when the hook caught it, so no box starts without what the
+         * hook meant to write.
+         */
+        const inWindow = async (hook, attempt, box, orderEnv) => {
+            const bound = new AbortController();
+            const timer = setTimeout(() => bound.abort(new PlaceError("UNHELD_FAILED", `the start window's hook overran its ${unheldMs} ms bound`)), unheldMs);
+            let open = true;
+            let closed;
+            /** Every put the hook started, settled or not: the driver starts only once all of them have settled. */
+            const pending = new Set();
+            const runControl = control;
+            const run = {
+                id: ref.id,
+                signal: bound.signal,
+                read: (path) => readRunFile(runControl, ref, path, { signal: bound.signal }),
+                list: (dir) => listRunFiles(runControl, ref, dir, { signal: bound.signal }),
+                put: (path, text) => {
+                    if (!open)
+                        return Promise.reject(new RunFileError("WINDOW_CLOSED", "the start window is closed (its hook returned or overran its bound): nothing more is put"));
+                    const put = putRunFile(runControl, ref, path, text, owner, { signal: bound.signal }).catch((error) => {
+                        if (error instanceof RunFileError && error.code === "WINDOW_CLOSED")
+                            closed ??= error;
+                        throw error;
+                    });
+                    const settled = put.then(() => undefined, () => undefined);
+                    pending.add(settled);
+                    void settled.then(() => pending.delete(settled));
+                    return put;
+                },
+            };
+            // The bound, as a rejection to race against.
+            const overran = new Promise((_, reject) => bound.signal.addEventListener("abort", () => reject(bound.signal.reason), { once: true }));
+            overran.catch(() => undefined);
+            let returned;
+            let thrown;
+            try {
+                returned = await Promise.race([Promise.resolve().then(() => hook(run, box ? { attempt, box } : { attempt })), overran]);
+            }
+            catch (error) {
+                thrown = { error };
+            }
+            // No put starts once the hook is done, and every put it started (awaited or not) settles inside the bound: none is
+            // written, or refused, after the driver has started.
+            open = false;
+            if (pending.size > 0) {
+                try {
+                    await Promise.race([Promise.allSettled([...pending]), overran]);
+                }
+                catch (error) {
+                    thrown ??= { error };
+                }
+            }
+            clearTimeout(timer);
+            if (closed)
+                throw new PlaceError("WINDOW_CLOSED", "a put in the start window was refused because a delegation holds the run (409 OperationAborted): this start makes no box", { cause: closed });
+            if (thrown) {
+                const { error } = thrown;
+                if (error === bound.signal.reason && error instanceof PlaceError)
+                    throw error;
+                if (error instanceof RunFileError && error.code === "CONTROL_API_FAILED")
+                    throw new PlaceError("CONTROL_API_FAILED", `the start window's hook failed on the control: ${error.message}`, { cause: error });
+                throw new PlaceError("UNHELD_FAILED", `the start window's hook failed: ${String(error?.message ?? error).slice(0, 400)}`, { cause: error });
+            }
+            if (returned === undefined)
+                return {};
+            if (returned === null || typeof returned !== "object" || Array.isArray(returned))
+                throw new PlaceError("INVALID_ARGUMENT", "the start window's hook returned something other than an environment (names to strings)");
+            const taken = new Set(["PATH", "PDA_HOLDER", "HOST_BOX", ...Object.keys(orderEnv)]);
+            for (const [name, value] of Object.entries(returned)) {
+                if (!ENV_NAME.test(name))
+                    throw new PlaceError("INVALID_ARGUMENT", `the start window's hook returned ${JSON.stringify(name)}, which is not an environment variable name`);
+                if (taken.has(name))
+                    throw new PlaceError("INVALID_ARGUMENT", `the start window's hook returned ${name}, which this start already sets (the driver, HOST_BOX or the order)`);
+                if (keyShaped(name))
+                    throw new PlaceError("INVALID_ARGUMENT", `the start window's hook returned ${name}, a secret's name (a KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL or CREDENTIALS segment): the instance can read its environment, so a secret never goes there`);
+                if (typeof value !== "string" || value.includes("\0"))
+                    throw new PlaceError("INVALID_ARGUMENT", `the start window's hook returned ${name} with a value that is not a string without NUL`);
+            }
+            return returned;
+        };
         const fetchedSizes = new Map();
         const carrying = new Map();
         const handleOf = new Map();
@@ -695,7 +798,14 @@ export function archilPlace(options) {
                 // Inside ensureRunning, after its revoke and start mark: no delegation holds the run, so S3 takes the writes.
                 start: async (r, token, attempt) => {
                     await makeDirs(order.gen);
-                    return host.start(r, token, { attempt: attempt?.attempt ?? order.gen, env: order.env });
+                    // The box this start makes is the next in `started`, so its index in status().boxes is started.length: its runner
+                    // claims that label first (HOST_BOX), for the supervisor's life (RUN_LABEL).
+                    const life = order.env.RUN_LABEL;
+                    const box = handingOver && typeof life === "string" && life !== "" ? { provider: host.provider, key: String(started.length), run: life } : undefined;
+                    const n = attempt?.attempt ?? order.gen;
+                    const added = options.unheld ? await inWindow(options.unheld, n, box, order.env) : {};
+                    const env = box ? { ...order.env, ...added, HOST_BOX: JSON.stringify(box) } : { ...order.env, ...added };
+                    return host.start(r, token, { attempt: n, env });
                 },
                 status: (h) => host.status(h),
                 stop: (h) => host.stop(h),
@@ -724,8 +834,15 @@ export function archilPlace(options) {
                     // An adopted instance mounts with an earlier start's token: this one is unused, removed as above.
                     if (result.adopted)
                         await drop(m).catch(() => { });
-                    handles.push(result.handle);
-                    started.push(result.handle);
+                    // A box this place already started, adopted again (its attempt started twice), keeps the key it has: a second
+                    // entry would be a key no runner claims (HOST_BOX), a box counted twice, and a box stopped twice. Only the driver
+                    // can say two handles are one instance (`instanceOf`); a box it cannot name, and every fresh one, is a new entry.
+                    const name = result.adopted === true ? host.instanceOf?.(result.handle) : undefined;
+                    const known = (list) => name !== undefined && list.some((h) => host.instanceOf?.(h) === name);
+                    if (!known(handles))
+                        handles.push(result.handle);
+                    if (!known(started))
+                        started.push(result.handle);
                     const w = watch(result.handle);
                     const mark = result.startMark ? await readStartMark(control, ref.id).catch(() => null) : null;
                     const runner = { epoch: mark?.generation ?? order.gen, exited: w.exited };
@@ -770,6 +887,13 @@ export function archilPlace(options) {
         return {
             name: "archil",
             paths,
+            // The run's own files over the control (GET, HEAD, LIST): never a mount, a write, or a wait on the claim.
+            ...(recording
+                ? {
+                    readRunFile: (path) => readRunFile(control, ref, path),
+                    listRunFiles: (dir) => listRunFiles(control, ref, dir),
+                }
+                : {}),
             kills: host.kill && host.kills ? [host.kills] : [],
             token: async (attempt) => (await mint(attempt)).token,
             ...(recording
@@ -823,7 +947,12 @@ export function archilPlace(options) {
                         throw error;
                     }),
                 ]);
-                const boxes = host.box ? started.map((h) => host.box(h)).filter((b) => b !== null) : undefined;
+                // With HOST_BOX in play a box's position is its key, so a box never drops out: no receipt fails the read instead.
+                const receipts = host.box ? started.map((h) => host.box(h)) : undefined;
+                const gap = receipts?.indexOf(null) ?? -1;
+                if (handingOver && gap >= 0)
+                    throw new PlaceError("STATUS_FAILED", `the driver gave no receipt for host box ${gap}, which this place started: every later box's key would shift`);
+                const boxes = receipts?.filter((b) => b !== null);
                 return { record, delegations: delegations.map(({ clientId, inodeId, path, isOrphaned, isPending }) => ({ clientId, inodeId, path, isOrphaned, isPending })), ...(boxes ? { boxes } : {}) };
             },
             recover: async (last, kind, order) => {

package/dist/run-files.d.ts

@@ -0,0 +1,72 @@
+import { type RunRef } from "./claim.js";
+import { PdaError } from "./errors.js";
+/** The calls of the disk's control these reads use; `archilControl` has all three. */
+export interface RunFileControl {
+    getObject(key: string): Promise<Uint8Array>;
+    /** null when there is no such key. */
+    headObject(key: string): Promise<unknown | null>;
+    listObjects(prefix: string, options?: {
+        recursive?: boolean;
+    }): Promise<{
+        objects: {
+            key: string;
+            size?: number;
+        }[];
+        commonPrefixes?: string[];
+    }>;
+}
+export type RunFileErrorCode = "INVALID_PATH" | "RUN_MISSING" | "NOT_A_FILE" | "CONTROL_API_FAILED" | "EXISTS" | "WINDOW_CLOSED";
+/** A read of a run's files that cannot be answered. Its message names the path, never what a file holds. */
+export declare class RunFileError extends PdaError {
+    readonly code: RunFileErrorCode;
+    constructor(code: RunFileErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The segments of `path`, or INVALID_PATH naming what is wrong (never the path). `""` is the run's root where allowed. */
+export declare function runFileSegments(path: string, allowRoot: boolean): string[];
+/**
+ * The bytes of `path` in the run (`runs/<id>/<path>`), or null when there is no such file yet, so a poller waits. A
+ * directory or a symlink is NOT_A_FILE; a run that does not exist is RUN_MISSING. No polling here: the caller bounds its
+ * own wait, with `signal` and its own retries.
+ */
+export declare function readRunFile(control: RunFileControl, ref: RunRef, path: string, options?: {
+    signal?: AbortSignal;
+}): Promise<Uint8Array | null>;
+/**
+ * The names directly under `dir` in the run (`""` for the run's root), sorted: files and directories alike, names only,
+ * never a claim about what each one is. A directory not made yet lists nothing; a run that does not exist is RUN_MISSING.
+ */
+export declare function listRunFiles(control: RunFileControl, ref: RunRef, dir: string, options?: {
+    signal?: AbortSignal;
+}): Promise<string[]>;
+/** The calls of the disk's control a put uses: HEAD, and PutObject with an owner. `archilControl` has both. */
+export interface RunFilePutControl {
+    headObject(key: string): Promise<unknown | null>;
+    putObject(key: string, body: string, options: {
+        uid: number;
+        gid: number;
+        mode: number;
+    }): Promise<unknown>;
+}
+/**
+ * Create `path` in the run (`runs/<id>/<path>`) holding `text`, owned by `owner` with mode 0644, after making each missing
+ * parent directory as a marker `owner` owns, mode 0755 (a directory made by path on a mount refuses later creates).
+ * Create-only: a file or a directory already at `path` is EXISTS and nothing is written. The check is a HEAD before the
+ * PutObject, not a conditional create (Archil's client has none), so it is not exclusive against another writer at the
+ * same moment: claim a shared name where a single writer is certain. Only a run nobody holds takes the write; a held one
+ * answers 409 OperationAborted, which is WINDOW_CLOSED. For non-secret run files: a put file is readable in the run.
+ */
+export declare function putRunFile(control: RunFilePutControl, ref: RunRef, path: string, text: string, owner: {
+    uid: number;
+    gid: number;
+}, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * `readRunFile` over the run directory `root` on this machine: the same path rules and answers. A directory, or a symlink
+ * anywhere on the way, is NOT_A_FILE, and a file swapped for a link after the check is refused, not followed.
+ */
+export declare function readLocalRunFile(root: string, id: string, path: string): Promise<Uint8Array | null>;
+/** `listRunFiles` over the run directory `root` on this machine: the same rules; a symlink on the way is NOT_A_FILE. */
+export declare function listLocalRunFiles(root: string, id: string, dir: string): Promise<string[]>;