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

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## Unreleased
 
+## 0.1.0-beta.16 (2026-10-18)
+
+- **A place's outcome carries the models the run's live parts chose (`PlaceOutcome.models`)**
+  - `PlaceOutcome.models?: Record<string, string>`: the role-to-model ids (`lead`, `eyes`, ...) the app reported, on any
+    outcome status, so a supervisor's manifest names the models of a remote run as of a local one.
+  - `archilPlace` reads it from `run.json`'s final status detail (`detail.models`); `localPlace` from the instance's
+    `{"outcome":...}` line, or from `run.json` without one.
+  - Both keep it only when it is a plain object whose values are all strings. A missing or malformed one is left out, never
+    replaced by `{}`. Before, `localPlace` passed the outcome line's `models` through unchecked, a malformed one included,
+    and `archilPlace` never carried it.
+- **`archilPlace.recordHome`: a runner on a box records into the run's disk, and the place brings the recording home**
+  - `Place.recordHome` (`PlaceRecordHome`): `dir(attempt)` is where that attempt's runner records, and
+    `bringHome(into, { final })` brings what it recorded into the supervisor's recording directory. `archilPlace` has
+    it when its control can list (`RecordControl`, as `archilControl` does); `localPlace` has none, since its runner
+    writes the supervisor's directory itself.
+  - `dir(attempt)` is `<root>/record/<attempt>`, inside the run's directory. `bringHome` reads it over S3 (list and get,
+    never the run's claim). Blobs come first, hash-checked and written whole; then the new whole lines of each
+    `.spool/*.jsonl` segment, with an offset per file name kept as what `into` already holds, so it is idempotent across
+    calls and processes. Carriers that overlap on one destination append each line once: one call at a time per
+    destination in a place, and a lock file per spool file across places and processes (a gone holder's is taken over;
+    one held past 5 s is `CARRY_FAILED`). Every write is carried to its last byte.
+  - With `ensure.create`, each start first makes the EMPTY `signals/`, `record/<attempt>/.spool/` and
+    `record/<attempt>/blobs/` over the control, owned by the run user (mode 0755), while no delegation holds the run. A
+    directory made by path on an Archil mount was seen to refuse file creates. Every file in them stays the runner's; a
+    refused put fails the start with `DIRS_REFUSED`.
+  - Box receipts: `HostDriver.box(handle)` (`HostBox`) and `PlaceStatus.boxes`. `archilPlace.status()` lists a receipt
+    for each box it started, released ones included: provider, kind, `from`, `to` and, when it has a price, the published
+    list price per second (`usdPerSecond`), the page it was read from (`source`) and the date read (`priced`). An unpriced
+    box has none of the three, never 0, and no field holds the provider's box id. `daytonaHost` reports its sandboxes, priced at `DAYTONA_LIST_PRICES`
+    (https://www.daytona.io/pricing, read 2026-10-16), with the "first 5 GiB free" applied to disk (the footnote's
+    placement is ambiguous). A box of unknown size has no price, nor does a box with a GPU, which the page prices per
+    model (`daytonaUsdPerSecond`). `localPlace` reports none.
+  - Failures carry codes (`PlaceError`). `BLOB_MISMATCH` is thrown after everything else came home. `CARRY_FAILED` is
+    thrown for a list or get that fails, and on `final` for a line whose blob never landed. `BOX_GONE` is never thrown
+    by this place: the recording lives on the disk, which outlives the box.
+- **A seed of any length stays in the supervisor's start grace**
+  - While a new run seeds it has no `run.json` heartbeat, and `ensureRunning` keeps a start in its grace only while the
+    start mark (`runs/<id>/start.json`) is younger than the grace (90 s by default). A longer seed was taken as a failed
+    start: revoked, then seeded again.
+  - Now, while the seed runs, the instance rewrites the mark's `at` every heartbeat through its claim (fsync and rename).
+    It does so only when a supervisor's mark for generation 1 is there, keeping its generation, `by`, `failures` and
+    `lastExit`. The rewrite runs on a thread of its own, one at a time, so a seed that blocks its thread (a synchronous
+    import) stays covered. It stops when the seed ends, before the open goes on, and `run.json`'s heartbeat takes over.
+  - A seeder that dies stops rewriting, and the grace runs out as for any start. The mark's format does not change.
+
 ## 0.1.0-beta.15 (2026-10-16)
 
 - **`HostDriver.kill`: take an instance away as a crash would, and `kills` says what that takes**

package/README.md

@@ -422,7 +422,13 @@ except after exit 65, 70, 75 or 76. `localHost({ mode: "child" })` runs a detach
 without that guarantee.
 
 `daytonaHost({ client, snapshot, ... })` runs each instance in a Daytona sandbox of its own (library only: `supervise`
-starts local units, so pass the driver to `ensureRunning`). The box comes from a snapshot that holds Node, the archil client
+starts local units, so pass the driver to `ensureRunning`). Its `box(handle)` is that sandbox's receipt: its size
+(vCPUs, memory, disk), when it was made and when the driver deleted it, and its list price per second at
+`DAYTONA_LIST_PRICES`. Those are Daytona's published rates, with the page and the date they were read
+(https://www.daytona.io/pricing, 2026-10-16): $0.0504 per vCPU-hour, $0.0162 per GiB-hour of memory and $0.000108 per
+GiB-hour of disk past the first 5 GiB, billed per second. The page's "first 5 free" footnote is applied to disk only (its
+placement is ambiguous). A box of unknown size gets no price, and neither does a box with a GPU: the page prices GPUs per
+model, which the driver doesn't map (`daytonaUsdPerSecond`). The box comes from a snapshot that holds Node, the archil client
 (`libfuse2`), this package, the run user and the sudoers drop-in, or from a default image that the caller's `prepare` installs
 them into. A container sandbox has no systemd (PID 1 is the Daytona daemon), so an in-box launcher keeps the instance
 alive in place and never restarts it after exit 0, 65, 70, 75 or 76. Every incarnation of an attempt gets the attempt's
@@ -757,10 +763,14 @@ await openDurableRun(ref, {
 - **When it fails.** A seed that throws fails the open with its own error. A process killed while it seeds leaves the run
   unpublished in the same way: no `run.json`, the claim let go. The next open seeds again, so a seed overwrites what an
   earlier attempt wrote.
-- **How long it may take.** Under a supervisor, a seed must end within the start grace (`--start-grace`,
-  `startGraceMs`; default the lease expiry, 90 s). Past it, `ensureRunning` takes the start as failed and revokes the
-  claim. The seed's next write or its barrier is then refused, the instance is fenced (exit 75) with nothing published,
-  and the next start seeds again. A deployment whose seeds can take longer raises the start grace.
+- **How long it may take.** A new run has no `run.json` heartbeat while it seeds. A supervisor keeps a start in its grace
+  (`--start-grace`, `startGraceMs`; default the lease expiry, 90 s) only while its start mark (`start.json`) is younger
+  than the grace. So while the seed runs, the instance rewrites the mark's time every heartbeat, through its claim, when a
+  supervisor's mark for generation 1 is there. It does so on a thread of its own, so a seed that holds its thread (a
+  synchronous import through `DatabaseSync`) is covered too. A live seed of any length stays `starting`. A seeder that dies stops
+  rewriting, the grace runs out as for any start, and the claim is revoked. If the claim is revoked while the seed still
+  runs, its next write or its barrier is refused, the instance is fenced (exit 75) with nothing published, and the next
+  start seeds again.
 - **On a local directory** (`localRun`) it is the same. As with `work/`, the files it writes are the operating system's
   to flush; a SQLite database it commits with `synchronous = FULL` is durable when the commit returns.
 
@@ -887,7 +897,35 @@ id and directory as the supervisor computed them.
   - A recovery is the takeover: the killed holder's delegations are revoked whatever its lease says, and the next
     instance starts. It reports `revoked` and `ms`. A newer incarnation than the one the place killed (another
     supervisor's) gets the usual lease and start-grace checks instead, so a live one is `HELD`, not revoked.
-  - `status()` reads `run.json` over S3 and lists the run's delegations.
+  - `status()` reads `run.json` over S3 and lists the run's delegations, plus, when its host driver makes boxes
+    (`daytonaHost`), a receipt for each box the place started, released ones included (`boxes`, `HostBox`). A receipt
+    has the provider, the kind, `from` and `to` (null while it lives). It also has the published list price per second
+    (`usdPerSecond`), the page that price was read from (`source`) and the ISO date it was read (`priced`). A box with
+    no price has none of those three, never a price of 0. No field holds the provider's id of the box.
+  - `recordHome` (when the control can list, as `archilControl`'s can): an attempt's runner records into
+    `recordHome.dir(attempt)`, `<root>/record/<attempt>`, in the run's directory, so its delegation covers it and
+    `deleteRunTree` removes it. `bringHome(into, { final })` reads that directory through the control (S3 list and get:
+    nothing takes the run's claim) and brings the recording into the supervisor's `into`.
+    - Blobs come first, each checked against the hash its name carries and written whole (a temporary file, fsync,
+      rename). One that doesn't match is skipped; everything else still comes home, then the call throws
+      `BLOB_MISMATCH`.
+    - Then the new whole lines of each `.spool/*.jsonl` segment, with an offset per file name: what `into` already
+      holds of it. So a second call, or a call from another process, brings nothing twice. A line waits while a blob it
+      names isn't home yet. On `final` it comes home anyway, and the call throws `CARRY_FAILED` naming the blob.
+    - Carriers that overlap on one `into` never append at once. The place runs one call at a time per destination, and
+      each append happens under a lock file beside its spool file (`.<name>.lock`, naming its holder's pid), after the
+      destination's size is read again, so only the lines past it are appended. A lock whose holder is gone is taken
+      over; one held past 5 s is `CARRY_FAILED`. A second `into` gets every line: what the place fetched for one
+      destination says nothing of another.
+    - A list or get that fails is `CARRY_FAILED`.
+    - The recording is on the disk, not in the box, so a final call after a box kill still brings home everything the
+      box fsynced: this place never throws `BOX_GONE`.
+    - With `ensure.create` (the run user's uid and gid), the place makes the EMPTY directories the runner writes into
+      at each start: `signals/`, `record/<attempt>/.spool/` and `record/<attempt>/blobs/`. It makes them over the
+      control, owned by the run user, mode 0755, in ensureRunning's window where no delegation holds the run. A
+      directory a process made by path on an Archil mount was seen to refuse file creates afterwards (ENOENT), and one
+      made over the control didn't. Every file in them stays the runner's. A refused put fails the start
+      (`DIRS_REFUSED`, as the cause of `HOST_START_FAILED`), and without an owner nothing is made.
   - `requestFile(attempt)` is `<root>/signals/kill-<attempt>.json`, in the run's directory and outside `work/`, and
     `signals(attempt)` reads `runs/<id>/signals/kill-<attempt>.json` over S3 every 500 ms (`signalPollMs`). A runner on
     a box of its own can't reach the supervisor's files, so its request travels through the disk. The runner must write
@@ -912,6 +950,11 @@ when the run is `done` and that detail carries a record, `failed` for anything e
 run its instance left `running`, `paused` or `sleeping`). So an app that runs on a box and wants its supervisor to have
 its record puts the record there, in its final `setStatus("done", { record })`.
 
+Either way the outcome may carry `models`, the role-to-model ids the run's live parts chose (`lead`, `eyes`, ...), on any
+status, a failed run's too: from the outcome line's `models`, or from the final detail's (`setStatus("done", { record,
+models })`). Both places keep it only when it is a plain object whose values are all strings; a missing or malformed one
+is left out, never replaced by `{}`.
+
 ## Tests
 
 ```sh

package/dist/hosts/daytona.d.ts

@@ -7,12 +7,37 @@ export type SandboxInfo = {
     id: string;
     name: string;
     state?: string;
+    /** The box's size as Daytona allocates it: vCPUs, GPUs, memory and disk (the API's GB). */
+    cpu?: number;
+    gpu?: number;
+    memory?: number;
+    disk?: number;
+    createdAt?: string;
     snapshot?: string;
     labels?: Record<string, string>;
     target?: string;
     toolboxProxyUrl?: string;
     errorReason?: string;
 };
+/**
+ * Daytona's published list prices, as its pricing page gave them on `readOn`: billed per second, quoted per hour, for
+ * each vCPU, each GiB of memory and each GiB of disk. The page's footnote "Price per GiB after first 5 free" is applied
+ * to storage (disk) only: its placement is ambiguous and could be read as covering memory too, so this is a choice.
+ * The page lists GPU rates per GPU model; this driver does not map a box's GPU to a model, so a GPU box is unpriced.
+ */
+export declare const DAYTONA_LIST_PRICES: {
+    readonly page: "https://www.daytona.io/pricing";
+    readonly readOn: "2026-10-16";
+    readonly vcpuPerHour: 0.0504;
+    readonly memoryGiBPerHour: 0.0162;
+    readonly diskGiBPerHour: 0.000108;
+    readonly freeDiskGiB: 5;
+};
+/**
+ * A box's list price per second at DAYTONA_LIST_PRICES, from its size; null when its size is unknown or it has a GPU
+ * (priced per GPU model on the page, which this driver does not map).
+ */
+export declare function daytonaUsdPerSecond(size: Pick<SandboxInfo, "cpu" | "gpu" | "memory" | "disk">): number | null;
 export type CreateSandboxBody = {
     name: string;
     snapshot: string;

package/dist/hosts/daytona.js

@@ -21,6 +21,32 @@ import { TERMINAL_EXITS } from "./local-host.js";
 export const DAYTONA_API_URL = "https://app.daytona.io/api";
 export const LABEL_FLEET = "pda-fleet";
 export const LABEL_RUN = "pda-run";
+/**
+ * Daytona's published list prices, as its pricing page gave them on `readOn`: billed per second, quoted per hour, for
+ * each vCPU, each GiB of memory and each GiB of disk. The page's footnote "Price per GiB after first 5 free" is applied
+ * to storage (disk) only: its placement is ambiguous and could be read as covering memory too, so this is a choice.
+ * The page lists GPU rates per GPU model; this driver does not map a box's GPU to a model, so a GPU box is unpriced.
+ */
+export const DAYTONA_LIST_PRICES = {
+    page: "https://www.daytona.io/pricing",
+    readOn: "2026-10-16",
+    vcpuPerHour: 0.0504,
+    memoryGiBPerHour: 0.0162,
+    diskGiBPerHour: 0.000108,
+    freeDiskGiB: 5,
+};
+/**
+ * A box's list price per second at DAYTONA_LIST_PRICES, from its size; null when its size is unknown or it has a GPU
+ * (priced per GPU model on the page, which this driver does not map).
+ */
+export function daytonaUsdPerSecond(size) {
+    const { cpu, memory, disk, gpu } = size;
+    const count = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+    if (!count(cpu) || !count(memory) || !count(disk) || (gpu !== undefined && gpu !== 0))
+        return null;
+    const p = DAYTONA_LIST_PRICES;
+    return (cpu * p.vcpuPerHour + memory * p.memoryGiBPerHour + Math.max(0, disk - p.freeDiskGiB) * p.diskGiBPerHour) / 3600;
+}
 export class DaytonaApiError extends PdaError {
     /** The HTTP status, null when no response arrived (network failure or timeout). */
     status;
@@ -256,6 +282,13 @@ export function daytonaHost(opts) {
             throw new DaytonaHostError("START_FAILED", `${what} in ${box.name} exited ${r.exitCode}: ${r.result.trim().split("\n").at(-1)?.slice(0, 300) ?? ""}`);
         return r;
     }
+    /** Each box this driver made, for its receipt: what Daytona said of it, when it was made, and when it ended. */
+    const made = new Map();
+    const ended = (id) => {
+        const m = made.get(id);
+        if (m && m.to === null)
+            m.to = new Date(now()).toISOString();
+    };
     return {
         fleet,
         mountRoot,
@@ -279,8 +312,10 @@ export function daytonaHost(opts) {
                 ...(opts.network?.allowList ? { networkAllowList: opts.network.allowList } : {}),
             };
             let box = await createOrAdopt(body, ref.id);
+            made.set(box.id, { info: box, from: box.createdAt ?? new Date(t0).toISOString(), to: null });
             try {
                 box = await waitStarted(box, t0 + startTimeoutMs);
+                made.get(box.id).info = { ...made.get(box.id).info, ...box };
                 const prepared = now();
                 if (opts.prepare)
                     await opts.prepare(box, client);
@@ -308,7 +343,9 @@ export function daytonaHost(opts) {
                 return handle;
             }
             catch (err) {
+                // The box was made and is deleted now: its receipt ends here, deleted or not (a delete that failed is the sweep's).
                 await client.remove(box.id).catch(() => { });
+                ended(box.id);
                 if (err instanceof DaytonaHostError)
                     throw err;
                 throw new DaytonaHostError("START_FAILED", `starting an instance in ${name} failed: ${err.message}`, { cause: err });
@@ -324,8 +361,10 @@ export function daytonaHost(opts) {
             catch (err) {
                 throw new DaytonaHostError("DAYTONA_API_FAILED", `reading sandbox ${h.name}: ${err.message}`, { cause: err });
             }
-            if (!box)
+            if (!box) {
+                ended(h.sandboxId);
                 return "gone";
+            }
             // The label, not the id in a handle, decides whose box this is: a handle can never reach another fleet's box.
             if (box.labels?.[LABEL_FLEET] !== fleet)
                 return "unknown";
@@ -366,6 +405,7 @@ export function daytonaHost(opts) {
                     throw new DaytonaHostError("STOP_FAILED", `deleting sandbox ${h.name} failed: ${err.message}`, { cause: first });
                 }
             }
+            ended(id);
         },
         async kill(h) {
             if (!mine(h))
@@ -394,6 +434,24 @@ export function daytonaHost(opts) {
                     throw new DaytonaHostError("KILL_FAILED", `deleting sandbox ${h.name} failed: ${err.message}`, { cause: first });
                 }
             }
+            ended(id);
+        },
+        box(h) {
+            if (!mine(h))
+                return null;
+            const m = made.get(h.sandboxId);
+            if (!m)
+                return null;
+            const { cpu, gpu, memory, disk } = m.info;
+            const usdPerSecond = daytonaUsdPerSecond(m.info);
+            const size = [cpu, memory, disk].every((n) => typeof n === "number") ? ` ${cpu} vCPU, ${memory} GiB memory, ${disk} GiB disk${gpu ? `, ${gpu} GPU` : ""}` : "";
+            return {
+                provider: "daytona",
+                kind: `sandbox${size}`,
+                from: m.from,
+                to: m.to,
+                ...(usdPerSecond === null ? {} : { usdPerSecond, source: DAYTONA_LIST_PRICES.page, priced: DAYTONA_LIST_PRICES.readOn }),
+            };
         },
     };
 }

package/dist/index.d.ts

@@ -18,17 +18,17 @@ export type { ArchilStore, Fence, FencedDatabase, Profile, StoreFencedError } fr
 export { AppError } from "./app.js";
 export type { AppContext, AppModule, AppOptions } from "./app.js";
 export { archilControl, deleteRunTree, ensureRunning, readRunStatus, SuperviseError } from "./supervise.js";
-export type { ArchilControl, CheckControl, CheckOptions, DiskClient, EnsureOptions, EnsureResult, HostDriver, HostHandle, HostStatus, Json, StartAttempt, StartReason, StonithOutcome, SuperviseErrorCode, SupervisorControl, TokenUser } from "./supervise.js";
+export type { ArchilControl, CheckControl, CheckOptions, DiskClient, EnsureOptions, EnsureResult, HostBox, HostDriver, HostHandle, HostStatus, Json, StartAttempt, StartReason, StonithOutcome, SuperviseErrorCode, SupervisorControl, TokenUser } from "./supervise.js";
 export { localHost, LocalHostError } from "./hosts/local-host.js";
 export type { LocalHostOptions, Ran, Runner } from "./hosts/local-host.js";
 export { dockerHost, DockerHostError } from "./hosts/docker.js";
 export type { ContainerInfo, DockerHostOptions, DockerRan, DockerRunner } from "./hosts/docker.js";
-export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./hosts/daytona.js";
+export { DAYTONA_LIST_PRICES, DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest, daytonaUsdPerSecond } from "./hosts/daytona.js";
 export type { CreateSandboxBody, DaytonaClient, DaytonaHostErrorCode, DaytonaHostOptions, DaytonaRestOptions, ExecResult, SandboxInfo } from "./hosts/daytona.js";
 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, PlaceRecovery, PlaceRunner, PlaceSignal, PlaceStatus, RunnerOrder } 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 { 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

@@ -17,7 +17,7 @@ export { AppError } from "./app.js";
 export { archilControl, deleteRunTree, ensureRunning, readRunStatus, SuperviseError } from "./supervise.js";
 export { localHost, LocalHostError } from "./hosts/local-host.js";
 export { dockerHost, DockerHostError } from "./hosts/docker.js";
-export { DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest } from "./hosts/daytona.js";
+export { DAYTONA_LIST_PRICES, DaytonaApiError, daytonaHost, DaytonaHostError, daytonaRest, daytonaUsdPerSecond } from "./hosts/daytona.js";
 // Serve: one HTTP request runs one turn.
 export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
 // Places: where a run lives for a supervisor that kills it and brings it back (agentrun's reference place seam).

package/dist/place.d.ts

@@ -1,7 +1,7 @@
 import type { Delegation } from "disk";
 import { PdaError } from "./errors.js";
 import { type RunRecord } from "./status.js";
-import { type EnsureOptions, type HostDriver, type SupervisorControl } from "./supervise.js";
+import { type EnsureOptions, type HostBox, type HostDriver, type SupervisorControl } from "./supervise.js";
 export type PlaceKill = "process" | "box";
 /** The run's paths in the place: its id, its directory, and the `work` and `store` under it. */
 export type PlacePaths = {
@@ -12,7 +12,8 @@ export type PlacePaths = {
 };
 /**
  * How the run stood when a runner ended: the instance's own report, or `run.json` as it left it. `status` is the run's
- * word: `complete` when it delivered, else `failed`.
+ * word: `complete` when it delivered, else `failed`. `models`, on any status: the role-to-model ids the run's live parts
+ * chose (`lead`, `eyes`, ...), when the app reported a plain object of strings; absent otherwise, never `{}` in its place.
  */
 export type PlaceOutcome = {
     status: string;
@@ -21,6 +22,7 @@ export type PlaceOutcome = {
     message?: string;
     record?: unknown;
     storeSha256?: string;
+    models?: Record<string, string>;
 };
 /** How a runner ended. `exit`: the exit code or signal (local), or the host's status (`stopped`, `failed`, `gone`) or `SIGKILL` when the place killed it (archil). */
 export type PlaceExit = {
@@ -42,9 +44,15 @@ export type RunnerOrder = {
     stdin?: string;
 };
 /** What the place reads of the run, the way it reads it: `run.json`, and on a disk the run's delegations. */
+/**
+ * What the place reads of the run, the way it reads it: `run.json`; on a disk, the run's delegations; and the boxes the
+ * place made for its runners, each as a receipt (`HostBox`: provider, kind, from, to, list price per second and where
+ * that price was read), when its host driver makes boxes. A box the place released stays listed with its end.
+ */
 export type PlaceStatus = {
     record: RunRecord | null;
     delegations?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned" | "isPending">[];
+    boxes?: HostBox[];
 };
 /** What a recovery did. A takeover on a disk lists what it revoked, and `ms` is the whole of it (revoke and start). */
 export type PlaceRecovery = {
@@ -91,6 +99,23 @@ export type PlaceContext = {
     destroyBoxes?: () => void | Promise<void>;
     requestFile?: (attempt: number) => string;
 };
+/**
+ * Where an attempt's runner records (its RECORD_DIR, in the place) and how the place brings that recording home. For a
+ * place whose runners cannot write the supervisor's recording directory.
+ */
+export interface PlaceRecordHome {
+    /** The directory, in the place, attempt `attempt`'s runner records into. */
+    dir(attempt: number): string;
+    /**
+     * Brings home into `into` what the runners recorded: blobs first, then the new whole lines of each `.spool/*.jsonl`.
+     * Idempotent; `final` is the call after the runner ended, when nothing is still landing.
+     */
+    bringHome(into: string, options?: {
+        final?: boolean;
+    }): Promise<void>;
+    /** How far the place's clock is from the supervisor's, when it knows. */
+    readonly clockSkewMs?: number;
+}
 export interface Place {
     /** `local` or `archil`, for the recording's lines. */
     readonly name: string;
@@ -122,8 +147,10 @@ export interface Place {
     move?(to: Place): Promise<Record<string, unknown>>;
     /** Lets the run go: stops what still runs (its commands too) and removes what the place made for it (tokens), never the run's directory. */
     release(): Promise<void>;
+    /** A place whose runners record where the supervisor cannot read says where, and brings the recording home. */
+    readonly recordHome?: PlaceRecordHome;
 }
-export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED";
+export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED" | "BOX_GONE" | "CARRY_FAILED" | "BLOB_MISMATCH" | "DIRS_REFUSED";
 export declare class PlaceError extends PdaError {
     constructor(code: PlaceErrorCode, message: string, options?: {
         cause?: unknown;
@@ -150,8 +177,11 @@ export declare function localPlace(options: LocalPlaceOptions): (ctx: PlaceConte
 export interface ArchilPlaceOptions {
     disk: string;
     region: string;
-    /** The disk's control API (`archilControl`). The place holds it; no instance ever does. */
-    control: SupervisorControl;
+    /**
+     * The disk's control API (`archilControl`). The place holds it; no instance ever does. With `listObjects` (as
+     * `archilControl` has), the place has `recordHome`.
+     */
+    control: SupervisorControl & Partial<RecordControl>;
     /**
      * The driver that runs the instance (`localHost`, `dockerHost`, `daytonaHost`), set up with the app the instance runs.
      * Its `kill` and `kills` are the place's.
@@ -175,6 +205,22 @@ export interface ArchilPlaceOptions {
      */
     signalFailMs?: number;
 }
+/** 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?: {
+        recursive?: boolean;
+    }): Promise<{
+        objects: {
+            key: string;
+            size?: number;
+        }[];
+    }>;
+}
+/**
+ * Every byte of `bytes` to `fd`: a write may take fewer bytes than it was given, so it goes on from where the last one
+ * stopped. A write that takes none fails, as one that throws (a full disk) does.
+ */
+export declare function writeAll(fd: number, bytes: Uint8Array, write?: (fd: number, bytes: Uint8Array, offset: number, length: number) => number): void;
 /**
  * The run on an Archil disk, its instance run by a host driver. `token(attempt)` mints the attempt's mount token through
  * the place's control, and the runner it is handed to mounts with it. A start is `ensureRunning` (it creates the run's

package/dist/place.js

@@ -5,8 +5,9 @@
 // place seam (examples/reference/place.ts) structurally. The supervisor reads nothing under the run's directory: the
 // outcome, the run's record and its delegations come through the place.
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { extname, join, posix, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
+import { dirname, extname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_MOUNT_ROOT, findDelegations, mintMountToken, pathlessResolver, removeMountToken, runPath } from "./claim.js";
 import { reapCommands } from "./commands.js";
@@ -48,6 +49,7 @@ function outcomeOf(record) {
         return undefined;
     const detail = record.detail !== null && typeof record.detail === "object" && !Array.isArray(record.detail) ? record.detail : {};
     const delivered = record.status === "done" && "record" in detail && detail.record !== null && detail.record !== undefined;
+    const models = modelsOf(detail.models);
     return {
         status: delivered ? "complete" : "failed",
         generation: record.generation,
@@ -55,8 +57,22 @@ function outcomeOf(record) {
         ...(typeof detail.message === "string" ? { message: detail.message } : {}),
         ...("record" in detail ? { record: detail.record } : {}),
         ...(typeof detail.storeSha256 === "string" ? { storeSha256: detail.storeSha256 } : {}),
+        ...(models ? { models } : {}),
     };
 }
+/**
+ * The role-to-model ids an outcome carries: a copy of `value` when it is a plain object whose values are all strings,
+ * else undefined, so a malformed report is left out and never stands in as `{}`.
+ */
+function modelsOf(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return undefined;
+    const entries = Object.entries(value);
+    return entries.every(([, id]) => typeof id === "string") ? Object.fromEntries(entries) : undefined;
+}
 const pathsUnder = (id, root) => ({ id, root, work: join(root, "work"), store: join(root, "store") });
 /**
  * The run on a directory of this machine: each runner is `pi-durable-disk run --dir <root> --id <id> --app <app>`, a
@@ -281,13 +297,20 @@ function requestIn(text) {
         return undefined;
     }
 }
-/** The `outcome` of a `{"outcome":{...}}` line with at least a status; undefined for any other line. */
+/**
+ * The `outcome` of a `{"outcome":{...}}` line with at least a status; undefined for any other line. Its `models` stays
+ * only when it is a plain object of strings (`modelsOf`), as `run.json`'s does.
+ */
 function outcomeLine(line) {
     if (!line.startsWith("{"))
         return undefined;
     try {
         const parsed = JSON.parse(line);
-        return parsed.outcome && typeof parsed.outcome === "object" && typeof parsed.outcome.status === "string" ? parsed.outcome : undefined;
+        if (!parsed.outcome || typeof parsed.outcome !== "object" || typeof parsed.outcome.status !== "string")
+            return undefined;
+        const { models: reported, ...outcome } = parsed.outcome;
+        const models = modelsOf(reported);
+        return models ? { ...outcome, models } : outcome;
     }
     catch {
         return undefined;
@@ -295,11 +318,263 @@ function outcomeLine(line) {
 }
 /** Where in the run's directory an Archil place's runners write their kill requests. */
 const REQUESTS = "signals";
-const requestName = (attempt) => {
+/** Where in the run's directory an Archil place's runners record, one directory per attempt. */
+const RECORDS = "record";
+const BLOB_NAME = /^([0-9a-f]{64})\.[A-Za-z0-9]{1,16}$/;
+const SPOOL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,200}\.jsonl$/;
+const NEWLINE = 0x0a;
+/** A message for a recording's line: at most 240 characters, so it never carries more than the line can hold. */
+const said = (text) => text.slice(0, MESSAGE_KEEP);
+/**
+ * Every byte of `bytes` to `fd`: a write may take fewer bytes than it was given, so it goes on from where the last one
+ * stopped. A write that takes none fails, as one that throws (a full disk) does.
+ */
+export function writeAll(fd, bytes, write = writeSync) {
+    for (let at = 0; at < bytes.length;) {
+        const n = write(fd, bytes, at, bytes.length - at);
+        if (!(n > 0))
+            throw new PlaceError("CARRY_FAILED", `a write took no bytes, ${bytes.length - at} of ${bytes.length} left`);
+        at += n;
+    }
+}
+/** `bytes` into `file` whole: a temporary file, fsync, rename, then the directory's fsync. */
+function writeWhole(file, bytes) {
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.${randomUUID()}.tmp`);
+    const fd = openSync(tmp, "wx", 0o644);
+    try {
+        writeAll(fd, bytes);
+        fsyncSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+    closeSync(fd);
+    renameSync(tmp, file);
+    syncDir(dir);
+}
+/** `bytes` at the end of `file`, fsynced; a file it creates is made durable in its directory too. */
+function appendDurably(file, bytes) {
+    const dir = dirname(file);
+    const created = !existsSync(file);
+    mkdirSync(dir, { recursive: true });
+    const fd = openSync(file, "a", 0o644);
+    try {
+        writeAll(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (created)
+        syncDir(dir);
+}
+/** How long a carrier waits for another one appending to the same destination file. */
+const CARRY_LOCK_WAIT_MS = 5_000;
+/** A lock file with no holder written yet (its taker is between the create and the write) counts as held this long. */
+const CARRY_LOCK_UNNAMED_MS = 10_000;
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/**
+ * `fn` while holding `lock`, a file created exclusively that names its holder's pid, so two carriers on one destination
+ * (two places, two processes) never append at once. A lock whose holder is gone (its process ended) is taken over; one a
+ * live holder keeps past CARRY_LOCK_WAIT_MS is CARRY_FAILED. `fn` is synchronous, so the lock is held only for it.
+ */
+async function withCarryLock(lock, fn) {
+    for (const t0 = Date.now();;) {
+        let fd;
+        try {
+            fd = openSync(lock, "wx", 0o644);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (fd !== undefined) {
+            // Once created, the lock goes on every way out: a failed write of the pid or close of the file included.
+            try {
+                try {
+                    writeAll(fd, new TextEncoder().encode(String(process.pid)));
+                }
+                finally {
+                    closeSync(fd);
+                }
+                fn();
+            }
+            finally {
+                rmSync(lock, { force: true });
+            }
+            return;
+        }
+        let holder = 0;
+        let ageMs = 0;
+        try {
+            holder = Number(readFileSync(lock, "utf8").trim());
+            ageMs = Date.now() - statSync(lock).mtimeMs;
+        }
+        catch (error) {
+            // Released meanwhile: take it on the next turn. Any other failure to read it (its mode, the disk) is the carry's.
+            if (error.code === "ENOENT" && Date.now() - t0 <= CARRY_LOCK_WAIT_MS)
+                continue;
+            throw new PlaceError("CARRY_FAILED", said(`reading the carry lock ${lock} failed: ${error?.message ?? error}`), { cause: error });
+        }
+        const gone = Number.isSafeInteger(holder) && holder > 0 ? !alive(holder) : ageMs > CARRY_LOCK_UNNAMED_MS;
+        if (gone) {
+            rmSync(lock, { force: true });
+            continue;
+        }
+        if (Date.now() - t0 > CARRY_LOCK_WAIT_MS)
+            throw new PlaceError("CARRY_FAILED", said(`another carrier (pid ${holder || "unnamed"}) holds ${lock} past ${CARRY_LOCK_WAIT_MS} ms`));
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+}
+function syncDir(dir) {
+    const fd = openSync(dir, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The blob hashes (SHA-256, hex) a recording's line names in its `blobs`; none for a line that is not JSON or names none. */
+function blobsOf(line) {
+    try {
+        const v = JSON.parse(new TextDecoder().decode(line));
+        return Array.isArray(v?.blobs) ? v.blobs.filter((b) => typeof b === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Brings home into `into` what the runners recorded under `prefix` (`runs/<id>/record/`), read through the control (S3
+ * ListObjects and GetObject: nothing takes the run's claim). It keeps no state: a blob is home when `into/blobs/<name>`
+ * exists, and a spool file's carried bytes are what `into/.spool/<name>` holds, so a second call, or a call from another
+ * process, carries nothing twice. Carriers that overlap on one destination never append at once: the place runs one call
+ * at a time per destination, and every append happens under a lock file beside its spool file (`.<name>.lock`, naming
+ * its holder's pid), where the destination's size is read again so only the lines past it are appended. A lock whose
+ * holder is gone is taken over; one held past 5 s is CARRY_FAILED. Every write is carried to its last byte.
+ * - Blobs first: each one not yet home is fetched, checked against the hash its name carries, and written whole into
+ *   `into/blobs`. One whose bytes do not match is skipped; everything else is brought home, then the call throws
+ *   BLOB_MISMATCH, and the next call tries that blob again.
+ * - Then lines: the new whole lines of each `.spool/<name>.jsonl`, the recorder's segments (`<stream>.<n>.jsonl`), each
+ *   with its own offset: what `into/.spool/<name>` already holds. A file is fetched only when it grew since this place
+ *   last fetched it (the SDK has no ranged read). A line whose blobs are not home yet waits for the next call, so no line arrives before its blob; on
+ *   `final` it is carried anyway, and its missing blobs are CARRY_FAILED once everything else is home.
+ * - A listing or fetch that fails is CARRY_FAILED. The recording is on the run's disk, not in the box, so a lost box
+ *   costs only what it had not fsynced: this place never throws BOX_GONE.
+ */
+async function carryHome(control, prefix, into, final, fetched) {
+    const fetch = async (key) => {
+        try {
+            return await control.getObject(key);
+        }
+        catch (error) {
+            throw new PlaceError("CARRY_FAILED", said(`reading ${key.slice(prefix.length)} of the run's recording failed: ${error?.message ?? error}`), { cause: error });
+        }
+    };
+    let objects;
+    try {
+        objects = (await control.listObjects(prefix, { recursive: true })).objects;
+    }
+    catch (error) {
+        throw new PlaceError("CARRY_FAILED", said(`listing the run's recording failed: ${error?.message ?? error}`), { cause: error });
+    }
+    // `<attempt>/blobs/<name>` and `<attempt>/.spool/<name>.jsonl`; anything else (`started`, a box's temporary file) is not carried.
+    const parts = (key) => key.slice(prefix.length).split("/");
+    const blobs = objects.filter((o) => {
+        const p = parts(o.key);
+        return p.length === 3 && p[1] === "blobs" && BLOB_NAME.test(p[2]);
+    });
+    const spools = objects.filter((o) => {
+        const p = parts(o.key);
+        return p.length === 3 && p[1] === ".spool" && SPOOL_NAME.test(p[2]);
+    });
+    const home = (name) => existsSync(join(into, "blobs", name));
+    const mismatched = [];
+    for (const blob of blobs) {
+        const name = parts(blob.key)[2];
+        if (home(name))
+            continue;
+        const bytes = await fetch(blob.key);
+        if (createHash("sha256").update(bytes).digest("hex") !== BLOB_NAME.exec(name)[1]) {
+            mismatched.push(name);
+            continue;
+        }
+        writeWhole(join(into, "blobs", name), bytes);
+    }
+    // A line names its blobs by hash; the file is `<hash>.<ext>`.
+    const homeHashes = new Set(existsSync(join(into, "blobs")) ? readdirSync(join(into, "blobs")).map((n) => BLOB_NAME.exec(n)?.[1]).filter((h) => h !== undefined) : []);
+    const waiting = new Set();
+    for (const spool of spools) {
+        const name = parts(spool.key)[2];
+        const dest = join(into, ".spool", name);
+        const carried = existsSync(dest) ? statSync(dest).size : 0;
+        // Not fetched again while its size is what this place last fetched and nothing in it waited for a blob (a partial
+        // last line keeps it bigger than what is home). Never skipped on `final`. Only a saving: what is home is still what
+        // the destination holds.
+        // Per destination: what this place fetched for one `into` says nothing of another.
+        const cacheKey = `${resolve(into)}\0${spool.key}`;
+        if (spool.size !== undefined && (spool.size <= carried || (!final && fetched.get(cacheKey) === spool.size)))
+            continue;
+        const bytes = await fetch(spool.key);
+        if (bytes.length <= carried)
+            continue;
+        let heldForBlob = false;
+        let end = carried;
+        for (let at = carried; at < bytes.length;) {
+            const nl = bytes.indexOf(NEWLINE, at);
+            if (nl < 0)
+                break; // a line still being written
+            const missing = blobsOf(bytes.subarray(at, nl)).filter((hash) => !homeHashes.has(hash));
+            if (missing.length > 0 && !final) {
+                heldForBlob = true;
+                break;
+            }
+            for (const b of missing)
+                waiting.add(b);
+            end = nl + 1;
+            at = nl + 1;
+        }
+        if (end > carried) {
+            // Another carrier on this destination (another place, another process) may have appended since `carried` was read.
+            // Under the file's lock, what the destination holds now decides: only the lines past it are appended.
+            mkdirSync(dirname(dest), { recursive: true });
+            await withCarryLock(join(dirname(dest), `.${name}.lock`), () => {
+                const now = existsSync(dest) ? statSync(dest).size : 0;
+                if (end > now)
+                    appendDurably(dest, bytes.subarray(now, end));
+            });
+        }
+        if (heldForBlob)
+            fetched.delete(cacheKey);
+        else
+            fetched.set(cacheKey, bytes.length);
+    }
+    if (mismatched.length > 0) {
+        throw new PlaceError("BLOB_MISMATCH", said(`${mismatched.length} blob(s) of the run's recording do not hash to their names: ${mismatched.join(", ")}`));
+    }
+    if (final && waiting.size > 0) {
+        throw new PlaceError("CARRY_FAILED", said(`${waiting.size} blob(s) the run's recording names never reached its disk: ${[...waiting].join(", ")}`));
+    }
+}
+const countFrom1 = (attempt) => {
     if (!Number.isSafeInteger(attempt) || attempt < 1)
         throw new PlaceError("INVALID_ARGUMENT", `attempt ${attempt} is not a count from 1`);
-    return `kill-${attempt}.json`;
+    return attempt;
 };
+const requestName = (attempt) => `kill-${countFrom1(attempt)}.json`;
 /**
  * The run on an Archil disk, its instance run by a host driver. `token(attempt)` mints the attempt's mount token through
  * the place's control, and the runner it is handed to mounts with it. A start is `ensureRunning` (it creates the run's
@@ -330,8 +605,40 @@ export function archilPlace(options) {
         const paths = { id: ref.id, root, work: posix.join(root, "work"), store: posix.join(root, "store") };
         const minted = new Map();
         const handles = [];
+        /** Every handle the place started, released or not: the boxes it reports. */
+        const started = [];
         const killed = new Map();
         let resolver = pathlessResolver(control);
+        const records = `${runPath(ref.id)}/${RECORDS}/`;
+        const recording = typeof options.control.listObjects === "function";
+        const owner = options.ensure?.create;
+        /**
+         * Before attempt `gen`'s runner starts: the EMPTY directories it writes into, `signals/` and, with `recordHome`,
+         * `record/<gen>/.spool/` and `record/<gen>/blobs/`, made over the control (PutObject with the owner, as createRunDir
+         * does: an exec mkdir would make them root's) and owned by the run user (`ensure.create`), in ensureRunning's window
+         * where no delegation holds the run (a held run refuses them: DIRS_REFUSED). A directory a process
+         * made by path on an Archil mount was seen to refuse file creates afterwards (ENOENT), and one made over the control
+         * does not. Every file in them stays the runner's (its kill request, its started, its spool), and a runner that
+         * makes them itself finds them made. Without an owner nothing is made: a directory the run user does not own would
+         * refuse the runner's files.
+         */
+        const makeDirs = async (gen) => {
+            if (!owner)
+                return;
+            const run = `${runPath(ref.id)}/`;
+            const dirs = [`${run}${REQUESTS}/`, ...(recording ? [`${run}${RECORDS}/`, `${run}${RECORDS}/${gen}/`, `${run}${RECORDS}/${gen}/.spool/`, `${run}${RECORDS}/${gen}/blobs/`] : [])];
+            for (const dir of dirs) {
+                try {
+                    if (!(await control.headObject(dir)))
+                        await control.putObject(dir, "", { uid: owner.uid, gid: owner.gid, mode: owner.mode ?? 0o755 });
+                }
+                catch (error) {
+                    throw new PlaceError("DIRS_REFUSED", said(`making ${dir.slice(run.length)} in the run over the control was refused: ${error?.message ?? error}`), { cause: error });
+                }
+            }
+        };
+        const fetchedSizes = new Map();
+        const carrying = new Map();
         const handleOf = new Map();
         const mint = async (attempt) => {
             const t = await mintMountToken(control, { run: { id: ref.id, attempt }, prefix: options.ensure?.tokenPrefix, ttl: options.ensure?.tokenTtl ?? TOKEN_TTL });
@@ -385,7 +692,11 @@ export function archilPlace(options) {
             const m = given && !given.removed ? given : await mint(order.gen);
             // The driver gets the order's environment with each start; everything else is the host's own.
             const driver = {
-                start: (r, token, attempt) => host.start(r, token, { attempt: attempt?.attempt ?? order.gen, env: order.env }),
+                // 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 });
+                },
                 status: (h) => host.status(h),
                 stop: (h) => host.stop(h),
             };
@@ -414,6 +725,7 @@ export function archilPlace(options) {
                     if (result.adopted)
                         await drop(m).catch(() => { });
                     handles.push(result.handle);
+                    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 };
@@ -460,6 +772,26 @@ export function archilPlace(options) {
             paths,
             kills: host.kill && host.kills ? [host.kills] : [],
             token: async (attempt) => (await mint(attempt)).token,
+            ...(recording
+                ? {
+                    recordHome: {
+                        // In the run's directory, so the runner's delegation covers it and deleteRunTree removes it.
+                        dir: (attempt) => posix.join(root, RECORDS, String(countFrom1(attempt))),
+                        // One carry at a time per destination in this place; another place or process is held off by the file lock.
+                        bringHome: (into, carry = {}) => {
+                            const key = resolve(into);
+                            const run = (carrying.get(key) ?? Promise.resolve()).catch(() => { }).then(() => carryHome(control, records, into, carry.final === true, fetchedSizes));
+                            const settled = run.then(() => { }, () => { });
+                            carrying.set(key, settled);
+                            void settled.then(() => {
+                                if (carrying.get(key) === settled)
+                                    carrying.delete(key);
+                            });
+                            return run;
+                        },
+                    },
+                }
+                : {}),
             // The request goes in the run's directory, outside work/ where the agent's tools are confined, and the place reads
             // it over S3: a runner on a box of its own cannot reach the supervisor's files.
             requestFile: (attempt) => posix.join(root, REQUESTS, requestName(attempt)),
@@ -491,7 +823,8 @@ export function archilPlace(options) {
                         throw error;
                     }),
                 ]);
-                return { record, delegations: delegations.map(({ clientId, inodeId, path, isOrphaned, isPending }) => ({ clientId, inodeId, path, isOrphaned, isPending })) };
+                const boxes = host.box ? started.map((h) => host.box(h)).filter((b) => b !== null) : undefined;
+                return { record, delegations: delegations.map(({ clientId, inodeId, path, isOrphaned, isPending }) => ({ clientId, inodeId, path, isOrphaned, isPending })), ...(boxes ? { boxes } : {}) };
             },
             recover: async (last, kind, order) => {
                 if (killed.has(last))

package/dist/run.js

@@ -15,7 +15,7 @@ import { archilEnv } from "./env.js";
 import { EXIT_FENCED, FencedError, HeldError, ownWriteFenced, PdaError } from "./errors.js";
 import { openArchilStore } from "./store.js";
 import { LeaseWatchdog } from "./watchdog.js";
-import { currentHolder, DEFAULT_HEARTBEAT_MS, DEFAULT_LEASE_EXPIRY_MS, DEFAULT_LEASE_MARGIN_MS, openClaimDir, persistRecord, readRunRecord, RUN_JSON, RunRecordError, writeRunRecord, } from "./status.js";
+import { currentHolder, DEFAULT_HEARTBEAT_MS, DEFAULT_LEASE_EXPIRY_MS, DEFAULT_LEASE_MARGIN_MS, keepStartMark, openClaimDir, persistRecord, readRunRecord, RUN_JSON, RunRecordError, writeRunRecord, } from "./status.js";
 /** The same-host owner lock under the run's root. */
 export const OWNER_LOCK = "owner.lock";
 /** pi's store under the claim's `store/` directory. */
@@ -358,7 +358,16 @@ class Lease {
         if (seed !== undefined && previous === undefined) {
             await step("seed", async () => {
                 await this.#dir.assertMounted();
-                await seed({ root: claim.root, storePath: join(claim.store, STORE_FILE), workDir: claim.work });
+                // While a new run seeds it has no `run.json` heartbeat, and a supervisor keeps a start in its grace only while its
+                // start mark is younger than the grace: the mark is kept fresh until the seed ends, through the held claim directory.
+                // A seeder that dies stops, and the grace runs out as for any start.
+                const stop = keepStartMark(this.#dir.at, this.#lease.heartbeatMs);
+                try {
+                    await seed({ root: claim.root, storePath: join(claim.store, STORE_FILE), workDir: claim.work });
+                }
+                finally {
+                    await stop();
+                }
                 await this.#dir.assertMounted();
                 await claim.barrier();
             });

package/dist/status.d.ts

@@ -81,6 +81,27 @@ export declare const persistRecord: PersistRecord;
  * `PersistRecord`.
  */
 export declare function writeRunRecord(root: string | ClaimDir, record: RunRecord, persist?: PersistRecord, signal?: AbortSignal): Promise<void>;
+/**
+ * The supervisor's record of its last start of a run, in the run's directory: the generation the instance will write,
+ * when, by whom, and the failed starts right before it (`failures`; `lastExit`, what the decision saw of the last one).
+ */
+export declare const START_MARK = "start.json";
+export type StartMark = {
+    generation: number;
+    at: string;
+    by: string | null;
+    failures: number;
+    lastExit: string | null;
+};
+/** A start mark's text as a mark, or null when it is not one (an unreadable mark gives no grace). */
+export declare function parseStartMark(text: string): StartMark | null;
+/**
+ * Keeps a supervisor's start mark for generation 1 in `dir` fresh: its `at` rewritten every `everyMs` (temp file, fsync,
+ * rename, fsync the directory), the rest of it as the supervisor wrote it; nothing is made when there is none. On a thread of
+ * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Best effort: a refused write leaves
+ * the mark as it was. Returns the stop, which resolves once the thread has exited, so no write outlives it.
+ */
+export declare function keepStartMark(dir: string, everyMs: number): () => Promise<void>;
 /** The FencedError code of a claim root that is no longer the mount the instance opened (unmounted, lazily or not). */
 export declare const CLAIM_UNMOUNTED = "CLAIM_UNMOUNTED";
 /** The file system type of an Archil mount in the mount table. */

package/dist/status.js

@@ -6,6 +6,7 @@ import { constants } from "node:fs";
 import { open, readFile, rename, rm, stat } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join } from "node:path";
+import { Worker } from "node:worker_threads";
 import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
 import { thisBoot } from "./process-table.js";
 export const RUN_JSON = "run.json";
@@ -158,6 +159,84 @@ export async function writeRunRecord(root, record, persist = persistRecord, sign
         throw ownWriteFenced(join(typeof root === "string" ? root : root.root, RUN_JSON), error);
     }
 }
+// ---- the supervisor's start mark --------------------------------------------------------------------------------------
+/**
+ * The supervisor's record of its last start of a run, in the run's directory: the generation the instance will write,
+ * when, by whom, and the failed starts right before it (`failures`; `lastExit`, what the decision saw of the last one).
+ */
+export const START_MARK = "start.json";
+/** A start mark's text as a mark, or null when it is not one (an unreadable mark gives no grace). */
+export function parseStartMark(text) {
+    try {
+        const v = JSON.parse(text);
+        if (!Number.isSafeInteger(v.generation) || v.generation < 1 || typeof v.at !== "string" || !Number.isFinite(Date.parse(v.at)))
+            return null;
+        const failures = Number.isSafeInteger(v.failures) && v.failures >= 0 ? v.failures : 0;
+        const lastExit = typeof v.lastExit === "string" ? v.lastExit : null;
+        return { generation: v.generation, at: v.at, by: typeof v.by === "string" ? v.by : null, failures, lastExit };
+    }
+    catch {
+        return null;
+    }
+}
+// The keeper's code is plain CommonJS in a string, started with `eval: true` and no inherited Node flags, as the lease
+// watchdog's is (src/watchdog.ts says why). One refresh at a time, all synchronous: a stop (the message) is handled only
+// between two refreshes, so none is still writing once the thread has exited.
+const KEEPER_SOURCE = `"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+const { parentPort, workerData } = require("node:worker_threads");
+const { dir, name, everyMs } = workerData;
+const file = path.join(dir, name);
+function refresh() {
+  try {
+    const mark = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (mark === null || typeof mark !== "object" || mark.generation !== 1 || typeof mark.at !== "string" || !Number.isFinite(Date.parse(mark.at))) return;
+    const temp = file + ".tmp";
+    const fd = fs.openSync(temp, "w", 0o644);
+    try {
+      fs.writeSync(fd, JSON.stringify({ ...mark, at: new Date().toISOString() }));
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+    const handle = fs.openSync(dir, "r");
+    try {
+      fs.fsyncSync(handle);
+    } finally {
+      fs.closeSync(handle);
+    }
+  } catch {
+    // absent, unreadable or refused
+  }
+}
+refresh();
+const timer = setInterval(refresh, everyMs);
+parentPort.once("message", () => {
+  clearInterval(timer);
+  parentPort.close();
+});
+`;
+/**
+ * Keeps a supervisor's start mark for generation 1 in `dir` fresh: its `at` rewritten every `everyMs` (temp file, fsync,
+ * rename, fsync the directory), the rest of it as the supervisor wrote it; nothing is made when there is none. On a thread of
+ * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Best effort: a refused write leaves
+ * the mark as it was. Returns the stop, which resolves once the thread has exited, so no write outlives it.
+ */
+export function keepStartMark(dir, everyMs) {
+    const worker = new Worker(KEEPER_SOURCE, { eval: true, workerData: { dir, name: START_MARK, everyMs }, execArgv: [] });
+    worker.unref();
+    worker.on("error", () => {
+        // the thread failed to start or threw: nothing more is refreshed, and the grace runs out as for any start
+    });
+    const exited = new Promise((resolve) => worker.once("exit", () => resolve()));
+    return () => {
+        worker.ref();
+        worker.postMessage("stop");
+        return exited;
+    };
+}
 // ---- the claim directory ----------------------------------------------------------------------------------------------
 /** The FencedError code of a claim root that is no longer the mount the instance opened (unmounted, lazily or not). */
 export const CLAIM_UNMOUNTED = "CLAIM_UNMOUNTED";

package/dist/supervise.d.ts

@@ -1,7 +1,7 @@
 import type { Delegation } from "disk";
 import { type ArchilHost, type ControlApi, type PathlessResolver, type RunRef } from "./claim.js";
 import { PdaError } from "./errors.js";
-import { type RunRecord } from "./status.js";
+import { type RunRecord, type StartMark } from "./status.js";
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -21,6 +21,22 @@ export type StartAttempt = {
     attempt: number;
     env?: Record<string, string>;
 };
+/**
+ * A box a driver made for an instance, as a receipt: who provided it, what kind, when it was made and when it ended
+ * (null while it lives), and its published list price per second (`usdPerSecond`), with the page that price was read
+ * from (`source`) and the ISO date it was read (`priced`). A box with no price (a kind the provider's page does not
+ * price, or of unknown size) has none of the three: never a price of 0. No field holds the provider's id of the box:
+ * the supervisor labels boxes itself and computes their seconds and cost.
+ */
+export type HostBox = {
+    provider: string;
+    kind: string;
+    from: string;
+    to: string | null;
+    usdPerSecond?: number;
+    source?: string;
+    priced?: string;
+};
 /** Compute is disposable and pluggable: a driver is these three calls. */
 export interface HostDriver {
     /**
@@ -41,6 +57,8 @@ export interface HostDriver {
     kill?(handle: HostHandle): Promise<void>;
     /** What `kill` takes: `process`, the instance's processes while its machine stays (a restart policy may bring them back), or `box`, its machine. */
     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;
 }
 /** The control-plane calls the supervisor uses; an archil `Disk` satisfies it. */
 export interface SupervisorControl extends ControlApi {
@@ -227,18 +245,7 @@ export type EnsureResult =
  * supervisors are safe: the mount admits one claimant and the other instance exits 76.
  */
 export declare function ensureRunning(ref: RunRef, host: HostDriver, options: EnsureOptions): Promise<EnsureResult>;
-/**
- * The supervisor's record of its last start of a run: the generation the instance will write, when, by whom, and the
- * failed starts right before it (`failures`; `lastExit`, what the decision saw of the last one).
- */
-export declare const START_MARK = "start.json";
-export type StartMark = {
-    generation: number;
-    at: string;
-    by: string | null;
-    failures: number;
-    lastExit: string | null;
-};
+export { START_MARK, type StartMark } from "./status.js";
 /** The grace of a start that follows `failures` failed ones: the base doubled per failure, capped, never below the base. */
 export declare function startGrace(baseMs: number, failures: number, maxMs?: number): number;
 /**

package/dist/supervise.js

@@ -8,7 +8,7 @@ import { hostname } from "node:os";
 import { join } from "node:path";
 import { acquire, createRunDir, findDelegations, matchDelegations, pathlessResolver, revokeBestEffort, revokeCompanions, mintMountToken, MOUNT_TOKEN_TTL, parseTokenNickname, removeMountToken, runPath, unmountClaim, } from "./claim.js";
 import { FencedError, HeldError, PdaError } from "./errors.js";
-import { parseRunRecord, RUN_JSON } from "./status.js";
+import { parseRunRecord, parseStartMark, RUN_JSON, START_MARK } from "./status.js";
 export const CONTROL_TIMEOUT_MS = 10_000;
 /** The same control API with every call bounded: one that does not settle in `ms` fails as CONTROL_API_FAILED. */
 export function withTimeouts(control, ms) {
@@ -160,11 +160,8 @@ export async function ensureRunning(ref, host, options) {
     await revokeListed(opts.control, ref.id, held, all);
     return start("lease-expired", held, stonith);
 }
-/**
- * The supervisor's record of its last start of a run: the generation the instance will write, when, by whom, and the
- * failed starts right before it (`failures`; `lastExit`, what the decision saw of the last one).
- */
-export const START_MARK = "start.json";
+// The start mark (`start.json`): its name, shape and parser live in status.ts, which the instance also reads it with.
+export { START_MARK } from "./status.js";
 /** The grace of a start that follows `failures` failed ones: the base doubled per failure, capped, never below the base. */
 export function startGrace(baseMs, failures, maxMs = START_BACKOFF_MAX_MS) {
     if (baseMs <= 0)
@@ -193,17 +190,7 @@ export async function readStartMark(control, id) {
             return null;
         throw new SuperviseError("CONTROL_API_FAILED", `GetObject ${runPath(id)}/${START_MARK} failed`, { cause: err });
     }
-    try {
-        const v = JSON.parse(text);
-        if (!Number.isSafeInteger(v.generation) || v.generation < 1 || typeof v.at !== "string" || !Number.isFinite(Date.parse(v.at)))
-            return null;
-        const failures = Number.isSafeInteger(v.failures) && v.failures >= 0 ? v.failures : 0;
-        const lastExit = typeof v.lastExit === "string" ? v.lastExit : null;
-        return { generation: v.generation, at: v.at, by: typeof v.by === "string" ? v.by : null, failures, lastExit };
-    }
-    catch {
-        return null;
-    }
+    return parseStartMark(text);
 }
 /** Only a run with no run.json and no holder gets here, so the directory is either absent or idle. */
 async function ensureRunDir(control, id, owner) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.15",
+  "version": "0.1.0-beta.16",
   "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
   "keywords": [
     "pi",
@@ -56,7 +56,7 @@
     "test": "node --test --test-timeout=240000 'test/*.test.ts' 'test/examples/*.test.ts'",
     "test:acceptance": "node --test --test-concurrency=1 'test/acceptance/*.test.ts'",
     "test:live": "node --test --test-concurrency=1 'test/live/*.test.ts'",
-    "test:live:claim": "node --test --test-concurrency=1 test/live/claim.live.test.ts",
+    "test:live:claim": "node --test --test-concurrency=1 test/live/claim.live.test.ts test/live/record-home.live.test.ts",
     "test:live:env": "node --test --test-concurrency=1 test/live/env.live.test.ts",
     "test:live:lifecycle": "node --test --test-concurrency=1 test/live/lifecycle.live.test.ts",
     "test:live:run": "node --test --test-concurrency=1 test/live/run.live.test.ts",