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

package/dist/run.d.ts

@@ -57,7 +57,21 @@ export interface LeaseOptions {
     /** How often the self-fence timer looks; default 1 s. */
     readonly checkMs?: number;
 }
-export type OpenStep = "acquire" | "owner-lock" | "run.json" | "heartbeat" | "layout" | "commands" | "store" | "seal" | "harness" | "live" | "before-resume" | "resume";
+export type OpenStep = "acquire" | "owner-lock" | "layout" | "commands" | "after-claim" | "seed" | "run.json" | "heartbeat" | "store" | "seal" | "harness" | "live" | "before-resume" | "resume";
+/** Where a new run's seed writes: the claim's root, the store file the Harness will open, and the workspace. */
+export interface RunSeedDir {
+    readonly root: string;
+    readonly storePath: string;
+    readonly workDir: string;
+}
+/**
+ * What a new run starts with, written before anything can see the run: its store file (`storePath`, a SQLite database
+ * the Harness then opens) and files in its workspace. It runs inside the run's first claim, holding the owner lock, after
+ * `store/`, `work/` and `tmp/` exist and `afterClaim` has run, and before `run.json` publishes the run. It never runs on a
+ * later open. If it throws (or its process dies) the open fails and nothing is published, so the next open seeds again: it
+ * must overwrite what an earlier attempt wrote. A connection it opens on `storePath` must be closed before it returns.
+ */
+export type RunSeed = (dir: RunSeedDir) => void | Promise<void>;
 export type ReleaseStep = "close" | "cleanup" | "barrier" | "seal" | "unlock" | "unmount";
 export interface OpenRunLeaseOptions {
     /**
@@ -104,12 +118,30 @@ export interface OpenRunLeaseOptions {
     readonly claimDir?: (root: string) => Promise<ClaimDir>;
     /** Replaceable for tests: the monotonic clock the self-fence measures with, in ms (default `performance.now`). */
     readonly clock?: () => number;
+    /**
+     * A new run's starting state (`RunSeed`): run once, on the open that finds no `run.json`, before `run.json` is written
+     * and the store opened; what it wrote is made durable (the claim's barrier) before the run is published.
+     */
+    readonly seed?: RunSeed;
 }
 export interface OpenDurableRunOptions<Tool extends ToolRegistration = ToolRegistration> extends Omit<OpenRunLeaseOptions, "cleanup"> {
     /** Default `exclusive`. */
     readonly profile?: Profile;
-    /** pi's Harness options; the registry holds every extension before the Harness opens (recovered tasks need them). */
-    readonly harness: Omit<HarnessOptions<Tool>, "env">;
+    /**
+     * pi's Harness options; the registry holds every extension before the Harness opens (recovered tasks need them).
+     * Required, here or from `afterClaim`.
+     */
+    readonly harness?: Omit<HarnessOptions<Tool>, "env">;
+    /**
+     * Awaited once the claim is held (the run's directory mounted, its owner lock taken, `store/`, `work/` and `tmp/` made,
+     * what a killed incarnation's commands left running reaped) and before this incarnation's `run.json`, with the claim's
+     * paths: what it returns (`harness`, `beforeResume`, a new run's `seed`) goes into the open, over what these options
+     * give; the seed runs right after it, on a new run only. For code that
+     * must run on the live directory, as an app module's factory does under the CLI. It runs before the heartbeat, inside a
+     * supervisor's start grace. A rejection fails the open with `run.json` as the open found it (none on a new run), so a
+     * supervisor counts a failed start and backs off; the claim is released.
+     */
+    readonly afterClaim?: (claim: Pick<Claim, "ref" | "root" | "work" | "store">) => Promise<AfterClaim<Tool>>;
     /** The run's environment, built on the claim; default `archilEnv(claim)`. Its `cleanup` is the lease's. */
     readonly env?: (claim: Claim) => RunEnv;
     /** Wraps the raw database inside the store's fence (instrumentation, fault injection). */
@@ -122,6 +154,13 @@ export interface OpenDurableRunOptions<Tool extends ToolRegistration = ToolRegis
      */
     readonly beforeResume?: (run: BeforeResume) => void | Promise<void>;
 }
+/** What `afterClaim` gives the open: the Harness options, the `beforeResume` hook and a new run's seed, when it holds them. */
+export interface AfterClaim<Tool extends ToolRegistration = ToolRegistration> {
+    readonly harness?: Omit<HarnessOptions<Tool>, "env">;
+    readonly beforeResume?: (run: BeforeResume) => void | Promise<void>;
+    /** A new run's seed, over the options' `seed`; ignored on an open that finds `run.json` (a resume). */
+    readonly seed?: RunSeed;
+}
 /**
  * What `beforeResume` sees: the open Harness, not yet resumed, the open's context, the incarnation it belongs to, and the
  * store the Harness was opened over with its head (a recorder snapshots every document at `head` here).
@@ -164,9 +203,10 @@ export interface RunClaim {
 }
 /**
  * The claim's lifecycle for an app that owns its store and Harness (`openDurableRun` without the store and the Harness). Open
- * order, all done by `openRunLease`: acquire and verify the claim, take the owner lock, write `run.json` (`running`,
- * generation + 1, this holder, a heartbeat, the previous seal kept), start the heartbeat and the self-fence (a timer and
- * a watchdog thread), create `store/`, `work/` and `tmp/`. The app then opens its store, calls `checkSeal` before
+ * order, all done by `openRunLease`: acquire and verify the claim, take the owner lock, create `store/`, `work/` and
+ * `tmp/`, reap what a killed incarnation's commands left running, seed a new run (`seed`), write `run.json` (`running`, generation + 1, this
+ * holder, a heartbeat, the previous seal kept), start the heartbeat and the self-fence (a timer and a watchdog thread).
+ * The app then opens its store, calls `checkSeal` before
  * anything commits, opens its Harness over `observe(storage)`, and calls `live()`. Once fenced, every member that
  * writes rejects with the first fence; nothing is retried.
  */
@@ -282,15 +322,16 @@ export interface StoreHeadSource {
  */
 export declare function storeHead(store: StoreHeadSource): Promise<number>;
 /**
- * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, write
- * `run.json` and start the heartbeat and the self-fence, create `store/`, `work/` and `tmp/`. Errors are typed as for
+ * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, create
+ * `store/`, `work/` and `tmp/`, reap a killed incarnation's commands, seed a new run, write `run.json` and start the
+ * heartbeat and the self-fence. Errors are typed as for
  * `openDurableRun`: HeldError (76), FencedError (75, also passed to `onFenced`), RunRecordError (65), RunError
  * INVALID_ARGUMENT before any claim.
  */
 export declare function openRunLease(ref: RunRef, options: OpenRunLeaseOptions): Promise<RunLease>;
 /**
- * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, `run.json`, heartbeat and
- * self-fence, layout), then the store, the seal check before anything commits, pi's Harness with the app's registry,
+ * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, layout, the commands reap, then
+ * `afterClaim`, a new run's seed, then `run.json`, heartbeat and self-fence), then the store, the seal check before anything commits, pi's Harness with the app's registry,
  * the seal cleared in `run.json`, resume.
  *
  * Errors are typed: HeldError (76) when another client, another process on this host or another connection holds the

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. */
@@ -311,12 +311,15 @@ class Lease {
         return this.#fence?.done ?? Promise.resolve();
     }
     /**
-     * The order after the claim. `run.json` is written (`running`, generation + 1, this holder, a heartbeat) and the
-     * heartbeat starts right after the owner lock, before the store and the Harness open, so a supervisor never sees the
-     * previous incarnation's stale heartbeat on a live claim. That first write keeps the previous `sealedSeq`, which the
-     * seal check still needs; `live()` clears it once the store is open.
+     * The order after the claim: the owner lock, the layout, the reap of a killed incarnation's commands, `afterClaim`
+     * (openDurableRun's), a new run's seed (afterClaim's over the options'), then `run.json` (`running`, generation + 1,
+     * this holder, a heartbeat) and the heartbeat, before
+     * the store and the Harness open. Nothing is published before that write: an open that fails earlier leaves `run.json`
+     * as it found it, so a supervisor counts a failed start and backs off; its start grace covers the steps before it.
+     * Once written, a supervisor never sees the previous incarnation's stale heartbeat on the live claim. That first write
+     * keeps the previous `sealedSeq`, which the seal check still needs; `live()` clears it once the store is open.
      */
-    async open(step, holder) {
+    async open(step, holder, afterClaim) {
         const claim = this.rawClaim;
         // SQLite resolves symbolic links in a file name, `/proc/self/fd/<n>` included, so `owner.lock` is the one file opened
         // by path: right after the mount check, and the file it names must then be the one in the claim directory.
@@ -341,6 +344,34 @@ class Lease {
         const previous = await this.#readPrevious();
         this.#previous = previous;
         this.#lastSeq = previous?.sealedSeq ?? 0;
+        await step("layout", () => this.#layout());
+        // A claim that records its commands (a local run's): end what a killed incarnation left running, before any code of
+        // this incarnation runs, so no command of it still writes in work/ once the run resumes. A process of it that outlives
+        // its SIGKILL refuses the open (HeldError, 76): the run never resumes beside it, and its record stays for the next open.
+        const commands = claim.commands;
+        if (commands !== undefined)
+            await step("commands", () => reapOrRefuse(commands));
+        const given = afterClaim ? await step("after-claim", () => afterClaim(claim)) : undefined;
+        // A new run (no run.json): its seed writes what it starts with, and only then is it published. afterClaim's seed
+        // goes over the options'.
+        const seed = given?.seed ?? this.#options.seed;
+        if (seed !== undefined && previous === undefined) {
+            await step("seed", async () => {
+                await this.#dir.assertMounted();
+                // 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();
+            });
+        }
         await step("run.json", async () => {
             const now = new Date().toISOString();
             this.#noteBeat(await this.#write(() => ({
@@ -366,19 +397,21 @@ class Lease {
                 ownCgroup: this.#options.ownCgroup === true,
             });
         });
-        await step("layout", async () => {
-            for (const dir of [claim.store, claim.work, join(claim.root, "tmp")]) {
-                const under = relative(claim.root, dir);
-                if (under === "" || under.startsWith("..") || isAbsolute(under))
-                    throw new RunError("INVALID_ARGUMENT", `${dir} is not under the claim root ${claim.root}`);
-                try {
-                    await mkdir(join(this.#dir.at, under), { recursive: true });
-                }
-                catch (error) {
-                    throw ownWriteFenced(dir, error);
-                }
+    }
+    /** `store/`, `work/` and `tmp/`, made through the held claim directory. */
+    async #layout() {
+        const claim = this.rawClaim;
+        for (const dir of [claim.store, claim.work, join(claim.root, "tmp")]) {
+            const under = relative(claim.root, dir);
+            if (under === "" || under.startsWith("..") || isAbsolute(under))
+                throw new RunError("INVALID_ARGUMENT", `${dir} is not under the claim root ${claim.root}`);
+            try {
+                await mkdir(join(this.#dir.at, under), { recursive: true });
             }
-        });
+            catch (error) {
+                throw ownWriteFenced(dir, error);
+            }
+        }
     }
     async checkSeal(store) {
         const sealed = this.sealedSeq;
@@ -611,7 +644,7 @@ class Lease {
             throw new RunError("RUN_RELEASED", `run ${this.ref.id} is released`);
     }
 }
-async function openLease(ref, options, step) {
+async function openLease(ref, options, step, afterClaim) {
     const context = options.context ?? BACKGROUND_CONTEXT;
     leaseOf(options.lease);
     let holder;
@@ -633,7 +666,7 @@ async function openLease(ref, options, step) {
     }));
     const lease = new Lease(ref, claim, options, context);
     try {
-        await lease.open(step, holder);
+        await lease.open(step, holder, afterClaim);
     }
     catch (error) {
         await lease.abandon(error);
@@ -642,8 +675,9 @@ async function openLease(ref, options, step) {
     return lease;
 }
 /**
- * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, write
- * `run.json` and start the heartbeat and the self-fence, create `store/`, `work/` and `tmp/`. Errors are typed as for
+ * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, create
+ * `store/`, `work/` and `tmp/`, reap a killed incarnation's commands, seed a new run, write `run.json` and start the
+ * heartbeat and the self-fence. Errors are typed as for
  * `openDurableRun`: HeldError (76), FencedError (75, also passed to `onFenced`), RunRecordError (65), RunError
  * INVALID_ARGUMENT before any claim.
  */
@@ -697,6 +731,7 @@ class Run {
         // Both refusals here are terminal: the run is marked `failed`, keeping its seal, so the supervisor stops on it.
         await step("seal", () => lease.checkSeal(this.#store));
         const storage = lease.observe(this.#store.storage);
+        // openDurableRun refused an open without Harness options (here or from afterClaim) before this runs.
         this.#harness = await step("harness", () => Harness.open(storage, { ...this.#options.harness, env: this.env }, this.#context));
         await step("live", () => lease.live());
         const before = this.#options.beforeResume;
@@ -749,8 +784,8 @@ class Run {
     }
 }
 /**
- * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, `run.json`, heartbeat and
- * self-fence, layout), then the store, the seal check before anything commits, pi's Harness with the app's registry,
+ * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, layout, the commands reap, then
+ * `afterClaim`, a new run's seed, then `run.json`, heartbeat and self-fence), then the store, the seal check before anything commits, pi's Harness with the app's registry,
  * the seal cleared in `run.json`, resume.
  *
  * Errors are typed: HeldError (76) when another client, another process on this host or another connection holds the
@@ -758,25 +793,32 @@ class Run {
  * RunError STORE_HEAD_UNREADABLE (70), each after marking the run `failed` and releasing the claim.
  */
 export async function openDurableRun(ref, options) {
+    if (!options.harness && !options.afterClaim)
+        throw new RunError("INVALID_ARGUMENT", "openDurableRun needs pi's Harness options, from its options or from afterClaim");
     const context = options.context ?? BACKGROUND_CONTEXT;
     const step = stepper(options.onStep);
     let env;
-    const lease = await openLease(ref, { ...options, context, cleanup: (c) => env?.cleanup(c) ?? Promise.resolve() }, step);
+    let opening = options;
+    const given = options.afterClaim;
+    // Inside the lease's open, before run.json: a factory that fails publishes nothing of this incarnation.
+    const afterClaim = given &&
+        (async ({ ref: claimRef, root, work, store }) => {
+            const got = await given({ ref: claimRef, root, work, store });
+            opening = { ...options, ...(got.harness ? { harness: got.harness } : {}), ...(got.beforeResume ? { beforeResume: got.beforeResume } : {}) };
+            if (!opening.harness)
+                throw new RunError("INVALID_ARGUMENT", "openDurableRun needs pi's Harness options: afterClaim returned none, and its options give none");
+            return got.seed ? { seed: got.seed } : {};
+        });
+    // The lease's cleanup is the environment's: abandoning the lease cleans both.
+    const lease = await openLease(ref, { ...options, context, cleanup: (c) => env?.cleanup(c) ?? Promise.resolve() }, step, afterClaim);
     try {
-        // A claim that records its commands (a local run's): end what a killed incarnation left running, now that the owner
-        // lock is held and before the Harness opens, so no command of it still writes in work/ once the run resumes.
-        const commands = lease.rawClaim.commands;
-        // A process of a killed incarnation that outlives its SIGKILL refuses the open (HeldError, 76): the run never resumes
-        // beside it, and its record stays for the next open.
-        if (commands !== undefined)
-            await step("commands", () => reapOrRefuse(commands));
         env = (options.env ?? ((c) => archilEnv(c)))(lease.rawClaim);
     }
     catch (error) {
         await lease.abandon(error);
         throw error;
     }
-    const run = new Run(lease, env, options, context);
+    const run = new Run(lease, env, opening, context);
     try {
         await run.open(step);
     }

package/dist/status.d.ts

@@ -55,6 +55,14 @@ export declare class RunRecordError extends PdaError {
 export declare function parseRunRecord(text: string): RunRecord;
 /** The `run.json` under a run's root on a local mount (or in a claim directory), or undefined when the run has none yet. */
 export declare function readRunRecord(root: string | ClaimDir): Promise<RunRecord | undefined>;
+/**
+ * The status of a run on a local directory (`localRun`): `<root>/run.json`, where `root` is the directory `localRun(root)`
+ * takes (not its `work/`). Read as `readRunStatus` reads a disk's through the control API: the same strict parser and the
+ * same `RunRecord`. It only reads: no lock, no mount and no store are touched, so it is safe beside a live instance, whose
+ * next write replaces the file whole. A run with no `run.json` yet, or no directory, is `null`; a record that is malformed
+ * is `RunRecordError` (`RUN_JSON_INVALID`); any other read error is thrown.
+ */
+export declare function readLocalRunStatus(root: string): Promise<RunRecord | null>;
 /**
  * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
  * clock skew between hosts inside the expiry.
@@ -73,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";
@@ -96,6 +97,16 @@ export async function readRunRecord(root) {
     }
     return parseRunRecord(text);
 }
+/**
+ * The status of a run on a local directory (`localRun`): `<root>/run.json`, where `root` is the directory `localRun(root)`
+ * takes (not its `work/`). Read as `readRunStatus` reads a disk's through the control API: the same strict parser and the
+ * same `RunRecord`. It only reads: no lock, no mount and no store are touched, so it is safe beside a live instance, whose
+ * next write replaces the file whole. A run with no `run.json` yet, or no directory, is `null`; a record that is malformed
+ * is `RunRecordError` (`RUN_JSON_INVALID`); any other read error is thrown.
+ */
+export async function readLocalRunStatus(root) {
+    return (await readRunRecord(root)) ?? null;
+}
 /**
  * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
  * clock skew between hosts inside the expiry.
@@ -148,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;
 };
@@ -12,9 +12,30 @@ export type HostHandle = {
     driver: string;
     [key: string]: Json;
 };
-/** Which start this is: the generation the instance will open (run.json's generation + 1), also in the token's nickname. */
+/**
+ * Which start this is: the generation the instance will open (run.json's generation + 1), also in the token's nickname.
+ * `env`: what this start adds to the instance's environment (a place's per-attempt order), merged over the driver's own
+ * `env`. PATH and PDA_HOLDER are the driver's: a start that sets either, or a name that is not a variable name, is refused.
+ */
 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 {
@@ -28,6 +49,16 @@ export interface HostDriver {
     status(handle: HostHandle): Promise<HostStatus>;
     /** Stop the instance and whatever it left on its host. A handle the driver cannot reach is a no-op. */
     stop(handle: HostHandle): Promise<void>;
+    /**
+     * Optional: take the instance away abruptly, as a crash would. No drain, no release, nothing cleaned: the run's claim is
+     * left as a crash leaves it (orphaned with its box, or held by a live mount until its lease lapses), and the
+     * supervisor's next pass decides what follows. A handle the driver cannot reach is a no-op.
+     */
+    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 {
@@ -73,6 +104,16 @@ export interface EnsureOptions {
     tokenTtl?: string;
     /** Prefix of each mount token's nickname. */
     tokenPrefix?: string;
+    /**
+     * A mount token the caller minted for this start (`mintMountToken`), for a caller that mints its own (a place's
+     * `token(attempt)`): a start uses it instead of minting one, and removes it as it would its own when the driver starts
+     * nothing or adopts. A decision that starts nothing leaves it to the caller.
+     */
+    mountToken?: {
+        token: string;
+        identifier: string;
+        nickname: string;
+    };
     /** The caller has work for the run now: start a paused run, or a sleeping one before its `wakeAt`. */
     demand?: boolean;
     /** Create `runs/<id>/` with this owner when it does not exist and nothing holds it. */
@@ -204,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) {
@@ -282,7 +269,7 @@ async function startInstance(ref, host, opts, why) {
     let token;
     try {
         // The attempt is the generation the instance will write, so the token user names the incarnation it served.
-        token = await mintMountToken(opts.control, { run: { id: ref.id, attempt: why.generation + 1 }, prefix: opts.tokenPrefix, ttl: opts.tokenTtl ?? TOKEN_TTL, now: opts.now });
+        token = opts.mountToken ?? await mintMountToken(opts.control, { run: { id: ref.id, attempt: why.generation + 1 }, prefix: opts.tokenPrefix, ttl: opts.tokenTtl ?? TOKEN_TTL, now: opts.now });
     }
     catch (err) {
         throw new SuperviseError("CONTROL_API_FAILED", `minting a mount token for ${runPath(ref.id)} failed`, { cause: err });