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

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## Unreleased
 
+## 0.1.0-beta.17 (2026-10-18)
+
+- **A claim directory's descriptor is closed by `close()` only, never by garbage collection (GRE-3853)**
+  - While a new run's seed waited on a promise nothing else held, the open's pending await chain was all that reached the
+    claim directory, so a collection could close its FileHandle. The start mark's keeper, which writes through
+    `/proc/self/fd/<n>` on a thread of its own, then failed silently, and the supervisor's grace ran out under a live seed.
+    A later open in the process could also be handed that number, and the keeper would have written the mark there.
+  - Every handle the package hands out as `/proc/self/fd/<n>` (the claim directory's `at`, a confined pin's paths, the walk
+    that makes them, the text line reader and the temp directory) is now held until it is closed.
+  - The keeper writes only while its directory is still the one it started on (same device and inode). If the directory
+    can't be reached or is another one, it stops. Its first failure is a process warning, code `PDA_START_MARK`, not
+    silence.
+
+## 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,15 @@ 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`. If the mark
+  can't be rewritten, the instance says so once, as a process warning with code `PDA_START_MARK`. 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 +898,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 +951,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/confine.js

@@ -20,6 +20,7 @@ import { constants, existsSync, realpathSync } from "node:fs";
 import { lstat, mkdir, open, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { err, FileError, ok } from "@earendil-works/pi-durable/env";
+import { fdPath, hold } from "./held-fd.js";
 /**
  * A file operation named a path that is not under the workspace (`outside_work`), or one whose components changed
  * while it was being resolved (`changed`). pi turns it into a failed tool result that names the path. Its `code` is pi's
@@ -153,7 +154,7 @@ export class Pin {
         this.name = name;
         this.#byPath = held.byPath;
         this.#names = held.names ?? [];
-        this.dir = held.byPath ? held.path : `/proc/self/fd/${handle.fd}`;
+        this.dir = held.byPath ? (hold(handle), held.path) : fdPath(handle);
         this.entry = dirMode ? this.dir : name === "" ? `${this.dir}/.` : `${this.dir}/${name}`;
         this.#real = dirMode || name === "" ? canonical : dirname(canonical);
     }
@@ -354,14 +355,14 @@ async function walk(root, names, create, canonical, byPath = false) {
     }
     try {
         // The root was opened by name: it must be the directory that name denotes now, not one swapped in on the way.
-        const actual = await readlink(`/proc/self/fd/${dir.fd}`);
+        const actual = await readlink(fdPath(dir));
         if (actual !== root)
             throw changed(canonical);
         let real = root;
         for (const name of names) {
             if (name === "" || name === "." || name === ".." || name.includes("\0"))
                 throw changed(canonical);
-            const step = `/proc/self/fd/${dir.fd}/${name}`;
+            const step = `${fdPath(dir)}/${name}`;
             real = join(real, name);
             let next;
             try {

package/dist/env.js

@@ -14,6 +14,7 @@ import { CodingTools } from "@earendil-works/pi-durable/tools";
 import { COMMANDS_MARK, CommandRecorder } from "./commands.js";
 import { canonicalizeSync, confineHooks, Confinement, fileError, inside, namesHeld, PathOutsideWorkError } from "./confine.js";
 import { PdaError } from "./errors.js";
+import { fdPath } from "./held-fd.js";
 /**
  * What `exec` returns once the factory's `cleanup()` ran: no command was started. Its `code` is pi's `spawn_error`
  * (the command could not start), `reason` tells it apart from a program that failed to spawn.
@@ -153,7 +154,7 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
         // pi opens the file again through the handle's own `/proc/self/fd` entry, which names that inode and no path; by path
         // (macOS), through the path just checked.
         const byPath = this.#scope.confinement.byPath;
-        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle, pin) => super.openTextLineReader(byPath ? pin.entry : `/proc/self/fd/${handle.fd}`, context));
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle, pin) => super.openTextLineReader(byPath ? pin.entry : fdPath(handle), context));
     }
     async openBinaryReader(path, options, context) {
         if (this.#scope.confinement === undefined)
@@ -314,7 +315,7 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
                 // By path (macOS): made under tmp/'s path once that path is checked to still name the directory held.
                 if (confinement.byPath && !(await namesHeld(tempRoot, held)))
                     throw new PathOutsideWorkError(tempRoot, "changed", `${tempRoot}: changed while it was being resolved`);
-                name = basename(await mkdtemp(`${confinement.byPath ? tempRoot : `/proc/self/fd/${held.fd}`}/${prefix ?? "tmp-"}`));
+                name = basename(await mkdtemp(`${confinement.byPath ? tempRoot : fdPath(held)}/${prefix ?? "tmp-"}`));
             }
             finally {
                 await held.close();

package/dist/held-fd.d.ts

@@ -0,0 +1,5 @@
+import type { FileHandle } from "node:fs/promises";
+/** Keeps `handle` reachable until it is closed. A handle held and never closed stays open until the process exits. */
+export declare function hold(handle: FileHandle): FileHandle;
+/** `/proc/self/fd/<n>` for `handle`, held until it is closed (`hold`). */
+export declare function fdPath(handle: FileHandle): string;

package/dist/held-fd.js

@@ -0,0 +1,14 @@
+const HELD = new Set();
+/** Keeps `handle` reachable until it is closed. A handle held and never closed stays open until the process exits. */
+export function hold(handle) {
+    if (!HELD.has(handle)) {
+        HELD.add(handle);
+        // A FileHandle is an EventEmitter that emits `close` once closed (Node's typings leave that out).
+        handle.once("close", () => HELD.delete(handle));
+    }
+    return handle;
+}
+/** `/proc/self/fd/<n>` for `handle`, held until it is closed (`hold`). */
+export function fdPath(handle) {
+    return `/proc/self/fd/${hold(handle).fd}`;
+}

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