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

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.1.0-beta.26 (2026-10-24)
+
+- Pin the Docker image, planned-move example and live-test sandbox setup to Archil client 0.10.0, with SHA-256 checks for each downloaded package. The client verifies server certificates against the operating system trust store and rejects certificates from the compromised eMudhra intermediate authorities. Linux hosts need client 0.10.0 or later and the operating system CA bundle installed (`ca-certificates` on Debian/Ubuntu); rebuild Docker images and sandbox snapshots to use the new client.
+- Archil's latest SDK: the package depends on the `disk` SDK 1.9.0 (was 1.7.0). The SDK calls the claim, lease and supervisor make are the same in 1.9.0, which adds disk branches and sandbox mounts. The client verbs the package runs take the same arguments in client 0.10.0, whose `mount` adds `--kernel-read-ahead-kb`. A host that installs `disk` itself installs 1.9.0, so npm keeps one copy.
+- `archilPlace({ unheld })` takes a hook that runs 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, once per start. It gets the start's `attempt` and, when the place hands labels over, exactly the `HOST_BOX` that start carries (`start.box`). It also gets the run's own files: `read`, `list`, and `put(path, text)`, which creates a file the run user owns (0644, parents 0755) and refuses a path already there with `EXISTS`. What it returns is added to that start's environment. It needs `ensure.create` and a control that lists. New types `UnheldHook`, `UnheldRun` and `UnheldStart`, and new `unheldTimeoutMs` (default 30 s).
+  - A put the hook does not await still settles inside the window: the driver starts only once every put has settled, within the hook's bound.
+  - `put` is a check, then a write, not a conditional create, so it is not exclusive between two supervisors in one window: put names unique to the start, and bind a shared name in the process that holds the run. It is for non-secret run files; a secret never goes through it.
+  - A start fails, and the driver starts no box, when a put was refused because the run is held (`WINDOW_CLOSED`, even if the hook caught it), when the hook throws a control failure (`CONTROL_API_FAILED`), when it throws anything else or overruns its bound (`UNHELD_FAILED`), or when its environment has a name the start already sets, 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 (`INVALID_ARGUMENT`, naming the variable, never its value). The caller sees `HOST_START_FAILED` with that `PlaceError` as its cause. `RunFileErrorCode` gains `EXISTS` and `WINDOW_CLOSED`; `PlaceErrorCode` gains `WINDOW_CLOSED`, `CONTROL_API_FAILED` and `UNHELD_FAILED`.
+  - Fix to merged behavior: a box the place already started and its driver adopts again (`adopted: true`, the same attempt started twice) keeps its key in `status().boxes`. New optional `HostDriver.instanceOf(handle)` names the instance a handle is for, the same for its fresh and its adopted handle; `dockerHost` (daemon and container name), `localHost` (host, boot, unit or tag) and `daytonaHost` (sandbox id) implement it, and without it no two handles are one box. It used to get a second entry: a key no runner claimed under `HOST_BOX`, the box counted twice in the receipts, and stopped twice at release.
+- `readRunFile(control, ref, path)` and `listRunFiles(control, ref, dir)` read a run's own files over the disk's control (S3 GET, HEAD and LIST): they never mount, write, or take or wait on the claim, so they read a run another host holds. `readRunFile` returns the bytes, or `null` for a file not written yet; `listRunFiles` returns the names directly under a directory, sorted, names only. Refusals are `RunFileError`: `INVALID_PATH` (before any request: absolute, `.`/`..`, unsafe characters, `.archil/`), `RUN_MISSING`, `NOT_A_FILE` (a directory, or a symlink, decided on Archil's 501 for it, never from a listing, where a symlink looks like an empty file), and `CONTROL_API_FAILED`. Both take a `signal`.
+  - A place offers the same reads of its own run: `Place.readRunFile(path)` and `Place.listRunFiles(dir)`, optional members that `archilPlace` implements over its control and `localPlace` over its run directory on this machine, where a symlink anywhere on the way is `NOT_A_FILE`, never followed. A missing file is `null`; a directory not there yet lists `[]`; every other failure throws.
+  - `INVALID_PATH` names what is wrong with a path (empty, absolute, a `.` or `..` segment, an unsafe character at an index, under `.archil/`), never the path itself.
+  - `archilPlace` tells each host box's runner which label to claim: when its driver makes boxes and names their provider (new optional `HostDriver.provider`; `daytonaHost` names `daytona`) and the place can read the label back (its control lists), each start puts `HOST_BOX` (`{ provider, key, run }`: the box's index in `status().boxes`, the order's `RUN_LABEL`) in that order's environment. With it, `status()` fails (`STATUS_FAILED`) on a box its driver gives no receipt for, instead of shifting the keys of the boxes after it.
+
 ## 0.1.0-beta.23 (2026-10-22)
 
 - The CLI's duration flags take a unit: `ms`, `s`, `m` or `h` (`500ms`, `30s`, `1.5m`, `1h`). A bare number used to mean milliseconds, so `--every 90` ran every 90 ms. It is now refused with exit 2 and a hint: `not a duration: "90": give a unit, e.g. 90s or 90ms`. Every duration flag a command is given is checked before the command acts. **Who breaks:** a script or service unit that passes a bare number to `--park-threshold`, `--park-idle`, `--drain-timeout`, `--stop-timeout`, `--control-timeout`, `--lease-expiry`, `--stonith-timeout`, `--start-grace`, `--start-backoff-max`, `--token-grace` or `--every`. **What to do:** add the unit you meant (`90ms` keeps today's behaviour).

package/dist/claim.d.ts

@@ -4,7 +4,7 @@ export type RunRef = {
     region: string;
     id: string;
 };
-/** The control-plane calls the claim uses; an archil `Disk` (SDK `disk` 1.7.0) satisfies it. Supervisor side only. */
+/** The control-plane calls the claim uses; an archil `Disk` (SDK `disk` 1.9.0) satisfies it. Supervisor side only. */
 export interface ControlApi {
     putObject(key: string, body: string, options: {
         uid: number;

package/dist/hosts/attempt-env.d.ts

@@ -1,3 +1,12 @@
 import type { StartAttempt } from "../supervise.js";
+/** A name an environment variable can have. */
+export declare const ENV_NAME: RegExp;
+/**
+ * Whether `name` is a secret's name: one of its `_`-separated segments, in any case, is KEY, TOKEN, SECRET, PASSWORD,
+ * PASSWD, CREDENTIAL or CREDENTIALS. Segments, not suffixes, so MODAL_TOKEN_ID is one too; CACHE_KEY_PREFIX is refused
+ * as well, and renamed, which is the cheaper error. A start's environment is readable in the instance, so a secret never
+ * goes there.
+ */
+export declare function keyShaped(name: string): boolean;
 /** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
 export declare function attemptEnv(attempt: StartAttempt | undefined, refuse: (message: string) => Error): Record<string, string>;

package/dist/hosts/attempt-env.js

@@ -1,5 +1,16 @@
-const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name an environment variable can have. */
+export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DRIVER_KEYS = new Set(["PATH", "PDA_HOLDER"]);
+const KEY_SEGMENTS = new Set(["KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD", "CREDENTIAL", "CREDENTIALS"]);
+/**
+ * Whether `name` is a secret's name: one of its `_`-separated segments, in any case, is KEY, TOKEN, SECRET, PASSWORD,
+ * PASSWD, CREDENTIAL or CREDENTIALS. Segments, not suffixes, so MODAL_TOKEN_ID is one too; CACHE_KEY_PREFIX is refused
+ * as well, and renamed, which is the cheaper error. A start's environment is readable in the instance, so a secret never
+ * goes there.
+ */
+export function keyShaped(name) {
+    return name.split("_").some((segment) => KEY_SEGMENTS.has(segment.toUpperCase()));
+}
 /** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
 export function attemptEnv(attempt, refuse) {
     const env = attempt?.env ?? {};

package/dist/hosts/daytona.d.ts

@@ -158,7 +158,7 @@ export interface DaytonaHostOptions {
 export declare function sandboxStatus(state: string | undefined): HostStatus | "check";
 /** A Daytona-safe box name for a run: lowercase, at most 63 characters, unique per call. */
 export declare function sandboxName(prefix: string, runId: string, now: number): string;
-export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly fleet: string;
     readonly mountRoot: string;
 };

package/dist/hosts/daytona.js

@@ -293,6 +293,8 @@ export function daytonaHost(opts) {
         fleet,
         mountRoot,
         kills: "box",
+        provider: "daytona",
+        instanceOf: (h) => (h.driver === "daytona" && typeof h.sandboxId === "string" ? `daytona\0${h.sandboxId}` : undefined),
         async start(ref, mountToken, attempt) {
             runPath(ref.id);
             if (!mountToken)

package/dist/hosts/docker.d.ts

@@ -95,7 +95,7 @@ export type ContainerInfo = {
     startedAt: string | null;
     finishedAt: string | null;
 };
-export declare function dockerHost(opts?: DockerHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function dockerHost(opts?: DockerHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly fleet: string;
     readonly mountRoot: string;
     describe(handle: HostHandle): Promise<ContainerInfo | null>;

package/dist/hosts/docker.js

@@ -272,6 +272,7 @@ export function dockerHost(opts = {}) {
         fleet,
         mountRoot,
         kills: "box",
+        instanceOf: (h) => (h.driver === "docker" && typeof h.daemon === "string" && typeof h.name === "string" ? `docker\0${h.daemon}\0${h.name}` : undefined),
         async start(ref, token, attemptInfo) {
             runPath(ref.id);
             if (!opts.image)

package/dist/hosts/local-host.d.ts

@@ -66,7 +66,7 @@ export declare function currentBootId(): string;
 export declare function parseShow(text: string): Record<string, string>;
 /** A unit's state as a host status: loaded and active (or restarting) is running; unloaded is gone. */
 export declare function unitStatus(show: Record<string, string>): HostStatus;
-export declare function localHost(opts?: LocalHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function localHost(opts?: LocalHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly hostName: string;
     readonly mountRoot: string;
 };

package/dist/hosts/local-host.js

@@ -357,6 +357,12 @@ 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

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[]>;

package/dist/run-files.js

@@ -0,0 +1,259 @@
+// A run's own files, read over the disk's control (S3 GET, HEAD and LIST) and nothing else: these calls never mount, never
+// write, and never take or wait on the run's claim, so anyone may read a run another host holds. A read sees what the
+// holder has synced (its last barrier), and a file the holder writes whole (a temp file, then a link or a rename) is never
+// seen half-written. What a file means is the reader's business: disk parses none of them. The one write here,
+// `putRunFile`, creates a file in a run nobody holds (a held run refuses it), for a place's start window.
+//
+// How Archil's S3 API answers, measured on archil 0.8.42: a missing key is 404; a directory is a marker key ending in "/";
+// a symlink is listed as an ordinary zero-byte key, but its HEAD and GET answer 501 NotImplemented, and S3 never follows a
+// link. So a symlink is told on a read's 501, never from a listing.
+import { constants } from "node:fs";
+import { lstat, open, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { runPath } from "./claim.js";
+import { PdaError } from "./errors.js";
+/** A read of a run's files that cannot be answered. Its message names the path, never what a file holds. */
+export class RunFileError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+/**
+ * What is wrong with `path` as a relative path of safe segments inside the run, or null when nothing is. The answer names
+ * the fault only, never the path, which may hold anything a caller passed.
+ */
+function pathFault(path, allowRoot) {
+    if (path === "")
+        return allowRoot ? null : "it is empty";
+    if (path.startsWith("/"))
+        return "it is absolute";
+    const unsafe = path.search(/[^A-Za-z0-9._/-]/);
+    if (unsafe >= 0)
+        return `it has an unsafe character at index ${unsafe}`;
+    const segments = path.split("/");
+    if (segments.includes(""))
+        return "it has an empty segment";
+    if (segments.includes("."))
+        return 'it has a "." segment';
+    if (segments.includes(".."))
+        return 'it has a ".." segment';
+    if (segments[0] === ".archil")
+        return "it is under .archil/";
+    return null;
+}
+/** The segments of `path`, or INVALID_PATH naming what is wrong (never the path). `""` is the run's root where allowed. */
+export function runFileSegments(path, allowRoot) {
+    const fault = pathFault(path, allowRoot);
+    if (fault !== null)
+        throw new RunFileError("INVALID_PATH", `not a relative path of safe segments (letters, digits, ".", "_", "-") inside the run: ${fault}`);
+    return path === "" ? [] : path.split("/");
+}
+/** The run's key prefix and `path` under it, or INVALID_PATH. */
+function keyOf(ref, path, allowRoot) {
+    const run = `${runPath(ref.id)}/`;
+    const segments = runFileSegments(path, allowRoot);
+    return { run, key: segments.length === 0 ? run : `${run}${segments.join("/")}` };
+}
+const statusOf = (error) => error?.status ?? error?.statusCode;
+const missing = (error) => statusOf(error) === 404 || error?.code === "NoSuchKey";
+const notImplemented = (error) => statusOf(error) === 501 || error?.code === "NotImplemented";
+/** `call`, ended at once when `signal` aborts (the request itself may still finish; nothing waits on it). */
+function bounded(call, signal) {
+    signal?.throwIfAborted();
+    // A control that throws before it returns a promise rejects like any other, so the listener below is always removed.
+    const pending = Promise.resolve().then(call);
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        pending.then((v) => (signal.removeEventListener("abort", onAbort), resolve(v)), (e) => (signal.removeEventListener("abort", onAbort), reject(e)));
+    });
+}
+/** A control call; any failure but the ones the caller handles is CONTROL_API_FAILED, an abort stays the caller's. */
+async function ask(what, call, signal) {
+    try {
+        return await bounded(call, signal);
+    }
+    catch (error) {
+        if (signal?.aborted && error === signal.reason)
+            throw error;
+        throw error instanceof RunFileError ? error : new RunFileError("CONTROL_API_FAILED", `${what} over the control failed`, { cause: error });
+    }
+}
+async function runMissing(control, run, ref, signal) {
+    if ((await ask(`reading ${run}`, () => control.headObject(run), signal)) === null)
+        throw new RunFileError("RUN_MISSING", `there is no run ${ref.id} on this disk`);
+}
+/**
+ * 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 async function readRunFile(control, ref, path, options = {}) {
+    const { signal } = options;
+    const { run, key } = keyOf(ref, path, false);
+    signal?.throwIfAborted();
+    try {
+        return await bounded(() => control.getObject(key), signal);
+    }
+    catch (error) {
+        if (signal?.aborted && error === signal.reason)
+            throw error;
+        if (notImplemented(error))
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${ref.id} is not a regular file (a symlink: the S3 API reads only files)`, { cause: error });
+        if (!missing(error))
+            throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${ref.id} over the control failed`, { cause: error });
+    }
+    // Not there: a directory of that name, no run at all, or a file not written yet.
+    if ((await ask(`reading ${path}/`, () => control.headObject(`${key}/`), signal)) !== null)
+        throw new RunFileError("NOT_A_FILE", `${path} in run ${ref.id} is a directory`);
+    await runMissing(control, run, ref, signal);
+    return 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 async function listRunFiles(control, ref, dir, options = {}) {
+    const { signal } = options;
+    const { run, key } = keyOf(ref, dir, true);
+    const prefix = key.endsWith("/") ? key : `${key}/`;
+    const listed = await ask(`listing ${dir || "the run"} of run ${ref.id}`, () => control.listObjects(prefix, { recursive: false }), signal);
+    const names = new Set();
+    for (const k of [...listed.objects.map((o) => o.key), ...(listed.commonPrefixes ?? [])]) {
+        if (!k.startsWith(prefix))
+            continue;
+        const name = k.slice(prefix.length).replace(/\/$/, "");
+        if (name !== "" && !name.includes("/"))
+            names.add(name);
+    }
+    if (names.size === 0)
+        await runMissing(control, run, ref, signal);
+    return [...names].sort();
+}
+/** A put Archil refused because a delegation holds the run: exactly 409 OperationAborted, as D2 measured on archil 0.8.42. */
+const windowClosed = (error) => statusOf(error) === 409 && error?.code === "OperationAborted";
+/**
+ * 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 async function putRunFile(control, ref, path, text, owner, options = {}) {
+    const { signal } = options;
+    const segments = runFileSegments(path, false);
+    const run = `${runPath(ref.id)}/`;
+    const key = `${run}${segments.join("/")}`;
+    const call = async (what, fn) => {
+        try {
+            return await bounded(fn, signal);
+        }
+        catch (error) {
+            if (signal?.aborted && error === signal.reason)
+                throw error;
+            if (windowClosed(error))
+                throw new RunFileError("WINDOW_CLOSED", `${what} was refused: a delegation holds run ${ref.id} (409 OperationAborted)`, { cause: error });
+            throw new RunFileError("CONTROL_API_FAILED", `${what} over the control failed`, { cause: error });
+        }
+    };
+    if ((await call(`reading ${path}`, () => control.headObject(key))) !== null || (await call(`reading ${path}/`, () => control.headObject(`${key}/`))) !== null) {
+        throw new RunFileError("EXISTS", `${path} is already in run ${ref.id}: a put creates, never replaces`);
+    }
+    for (let i = 1; i < segments.length; i++) {
+        const dir = segments.slice(0, i).join("/");
+        if ((await call(`reading ${dir}/`, () => control.headObject(`${run}${dir}/`))) === null) {
+            await call(`making ${dir}/`, () => control.putObject(`${run}${dir}/`, "", { uid: owner.uid, gid: owner.gid, mode: 0o755 }));
+        }
+    }
+    await call(`writing ${path}`, () => control.putObject(key, text, { uid: owner.uid, gid: owner.gid, mode: 0o644 }));
+}
+// ---- the same reads over a run directory on this machine (localPlace) -------------------------------------------------
+const fsCode = (error) => error?.code;
+async function localRunMissing(root, id) {
+    try {
+        if ((await stat(root)).isDirectory())
+            return;
+    }
+    catch (error) {
+        if (fsCode(error) !== "ENOENT" && fsCode(error) !== "ENOTDIR")
+            throw new RunFileError("CONTROL_API_FAILED", `reading run ${id} failed`, { cause: error });
+    }
+    throw new RunFileError("RUN_MISSING", `there is no run ${id} on this machine`);
+}
+/**
+ * Walk `segments` under `root` with lstat: a symlink anywhere on the way is NOT_A_FILE (never followed, so nothing outside
+ * the run is ever read). Resolves with the last path and what it is, or null when something on the way is not there.
+ */
+async function walk(root, id, path, segments) {
+    let at = root;
+    for (const [i, segment] of segments.entries()) {
+        at = join(at, segment);
+        let st;
+        try {
+            st = await lstat(at);
+        }
+        catch (error) {
+            if (fsCode(error) === "ENOENT" || fsCode(error) === "ENOTDIR")
+                return null;
+            throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${id} failed`, { cause: error });
+        }
+        if (st.isSymbolicLink())
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} goes through a symlink, which is never followed`);
+        if (i < segments.length - 1 && !st.isDirectory())
+            return null;
+        if (i === segments.length - 1)
+            return { at, dir: st.isDirectory() };
+    }
+    return { at, dir: true };
+}
+/**
+ * `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 async function readLocalRunFile(root, id, path) {
+    const segments = runFileSegments(path, false);
+    await localRunMissing(root, id);
+    const found = await walk(root, id, path, segments);
+    if (!found)
+        return null;
+    if (found.dir)
+        throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is a directory`);
+    let handle;
+    try {
+        handle = await open(found.at, constants.O_RDONLY | constants.O_NOFOLLOW);
+        if (!(await handle.stat()).isFile())
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is not a regular file`);
+        return new Uint8Array(await handle.readFile());
+    }
+    catch (error) {
+        if (error instanceof RunFileError)
+            throw error;
+        if (fsCode(error) === "ELOOP")
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is a symlink, which is never followed`);
+        if (fsCode(error) === "ENOENT")
+            return null;
+        throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${id} failed`, { cause: error });
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** `listRunFiles` over the run directory `root` on this machine: the same rules; a symlink on the way is NOT_A_FILE. */
+export async function listLocalRunFiles(root, id, dir) {
+    const segments = runFileSegments(dir, true);
+    await localRunMissing(root, id);
+    const found = await walk(root, id, dir, segments);
+    if (!found || !found.dir)
+        return [];
+    try {
+        return (await readdir(found.at)).sort();
+    }
+    catch (error) {
+        if (fsCode(error) === "ENOENT" || fsCode(error) === "ENOTDIR")
+            return [];
+        throw new RunFileError("CONTROL_API_FAILED", `listing ${dir || "the run"} of run ${id} failed`, { cause: error });
+    }
+}

package/dist/supervise.d.ts

@@ -59,6 +59,18 @@ export interface HostDriver {
     readonly kills?: "process" | "box";
     /** Optional, for a driver whose instances get machines of their own: the box `handle`'s instance runs in, as a receipt. */
     box?(handle: HostHandle): HostBox | null;
+    /**
+     * Optional, with `box`: the provider of the boxes this driver makes (its receipts' `provider`), known before a box
+     * exists. A place tells each host box's runner which label to claim by it (`HOST_BOX`).
+     */
+    readonly provider?: string;
+    /**
+     * Optional: the name of the instance `handle` is for, the same for its fresh handle and an adopted one (dockerHost: the
+     * daemon and the container's name), or `undefined` for a handle that is not this driver's or names none. A place keys
+     * the boxes it started by it, so a box adopted again keeps its key. Two handles are one instance only when this names
+     * them both, equally: without it no two handles ever are.
+     */
+    instanceOf?(handle: HostHandle): string | undefined;
 }
 /** The control-plane calls the supervisor uses; an archil `Disk` satisfies it. */
 export interface SupervisorControl extends ControlApi {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.23",
+  "version": "0.1.0-beta.26",
   "description": "The agent is the workspace: its conversation and its files live together in one directory on a disk. Mount it on any Linux host or container, release it, and mount it elsewhere: the agent carries on.",
   "keywords": [
     "pi",
@@ -72,7 +72,7 @@
     "@earendil-works/pi-durable": ">=1.0.4 <1.4.0"
   },
   "dependencies": {
-    "disk": "1.7.0"
+    "disk": "1.9.0"
   },
   "devDependencies": {
     "@earendil-works/chord": "1.1.0",