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

package/dist/process-table.js

@@ -0,0 +1,158 @@
+// The process table a run reads to know its commands and its holder. On Linux it is /proc, read live. macOS has no /proc:
+// there it is one ps(1) listing per look, ps for a process's environment, and sysctl(8) for the boot. A process's start
+// tells it from a later process with the same pid: on Linux its start time in clock ticks after boot (field 22 of
+// /proc/<pid>/stat), on macOS the second it started (ps's `lstart`, read in UTC). A start is only ever compared with
+// another read on the same machine and boot. On macOS a pid freed and handed out again within the same second would pass
+// for the old process; pids there are handed out in order up to 99999 before one is reused.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The table on Linux: `/proc` (or another directory laid out like it, for tests). */
+export function procTable(proc = "/proc") {
+    const read = (...parts) => readFileSync(join(proc, ...parts), "utf8");
+    const snapshot = {
+        // `stat`'s fields after the last `)`, since the command name may hold spaces and parentheses.
+        info(pid) {
+            try {
+                const text = read(String(pid), "stat");
+                const fields = text.slice(text.lastIndexOf(")") + 2).split(" ");
+                if (fields[0] === "Z" || fields[0] === "X")
+                    return undefined;
+                return { ppid: Number(fields[1]), pgrp: Number(fields[2]), start: Number(fields[19]) };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        // From each of its threads' `children` list.
+        children(pid) {
+            let tasks;
+            try {
+                tasks = readdirSync(join(proc, String(pid), "task"));
+            }
+            catch {
+                return [];
+            }
+            return tasks.flatMap((tid) => {
+                try {
+                    return read(String(pid), "task", tid, "children").split(" ").filter(Boolean).map(Number);
+                }
+                catch {
+                    return [];
+                }
+            });
+        },
+        marked(pid, name, value) {
+            try {
+                return read(String(pid), "environ").split("\0").includes(`${name}=${value}`);
+            }
+            catch {
+                return false;
+            }
+        },
+        commandLine(pid) {
+            try {
+                return read(String(pid), "cmdline").split("\0").filter(Boolean).join(" ") || "?";
+            }
+            catch {
+                return "?";
+            }
+        },
+    };
+    return {
+        snapshot: () => snapshot,
+        bootId() {
+            try {
+                return read("sys/kernel/random/boot_id").trim() || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        walkMs: 100,
+    };
+}
+const PS = "/bin/ps";
+const SYSCTL = "/usr/sbin/sysctl";
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** In the C locale and UTC, so `lstart` reads the same whatever the user's settings. */
+const runCommand = (file, args) => execFileSync(file, args, { encoding: "utf8", env: { LC_ALL: "C", TZ: "UTC" }, stdio: ["ignore", "pipe", "ignore"], timeout: 10_000, maxBuffer: 64 << 20 });
+/**
+ * One line of `ps -A -o pid=,ppid=,pgid=,stat=,lstart=` in UTC: `pid ppid pgid stat Www Mmm dd hh:mm:ss yyyy`. Null
+ * for a zombie; throws on a line it does not read.
+ */
+function psLine(line) {
+    const f = line.trim().split(/\s+/);
+    const [pid, ppid, pgrp] = f.slice(0, 3).map(Number);
+    const month = MONTHS.indexOf(f[5] ?? "");
+    const [h, m, s] = (f[7] ?? "").split(":").map(Number);
+    const start = Date.UTC(Number(f[8]), month, Number(f[6]), h, m, s) / 1000;
+    if (f.length !== 9 || ![pid, ppid, pgrp, start].every(Number.isSafeInteger) || month < 0)
+        throw new Error(`ps printed a line this does not read: ${JSON.stringify(line)}`);
+    return f[3].startsWith("Z") ? null : [pid, { ppid: ppid, pgrp: pgrp, start }];
+}
+/** The table on macOS: `ps` and `sysctl`, through `run` (for tests). */
+export function psTable(run = runCommand) {
+    let boot;
+    return {
+        snapshot() {
+            const rows = new Map();
+            for (const line of run(PS, ["-A", "-o", "pid=,ppid=,pgid=,stat=,lstart="]).split("\n")) {
+                if (line.trim() === "")
+                    continue;
+                const row = psLine(line);
+                if (row !== null)
+                    rows.set(...row);
+            }
+            return {
+                info: (pid) => rows.get(pid),
+                children: (pid) => [...rows].filter(([, info]) => info.ppid === pid).map(([child]) => child),
+                // `-E` prints the environment the process was started with after its arguments, separated by spaces; a mark is
+                // a name and a UUID, which hold none.
+                marked(pid, name, value) {
+                    try {
+                        return run(PS, ["-ww", "-E", "-p", String(pid), "-o", "command="]).split(/\s+/).includes(`${name}=${value}`);
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                commandLine(pid) {
+                    try {
+                        return run(PS, ["-ww", "-p", String(pid), "-o", "command="]).trim() || "?";
+                    }
+                    catch {
+                        return "?";
+                    }
+                },
+            };
+        },
+        // Read once it can be: a boot's id does not change.
+        bootId() {
+            try {
+                boot ??= run(SYSCTL, ["-n", "kern.bootsessionuuid"]).trim() || undefined;
+            }
+            catch {
+                // not now; the next call asks again
+            }
+            return boot;
+        },
+        walkMs: 500,
+    };
+}
+/** Test seam: a table that stands in for this machine's everywhere `processTable()` is read. */
+export const processTableHooks = {};
+let platformTable;
+/** This machine's table: ps on macOS, /proc elsewhere. */
+export function processTable() {
+    if (processTableHooks.table !== undefined)
+        return processTableHooks.table;
+    if (platformTable?.platform !== process.platform) {
+        platformTable = { platform: process.platform, table: process.platform === "darwin" ? psTable() : procTable() };
+    }
+    return platformTable.table;
+}
+/** This boot's id on this machine, null when it cannot be read. */
+export function thisBoot() {
+    return processTable().bootId() ?? null;
+}

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).
@@ -130,7 +169,15 @@ export interface BeforeResume {
     readonly harness: Harness;
     readonly context: Context;
     readonly generation: number;
+    /** This incarnation's `run.json`, which the open has already written (`running`, this holder, `detail` null). */
     readonly record: RunRecord;
+    /**
+     * `run.json` as it was before this open wrote over it: how the run was left. After a park it is `sleeping` with its
+     * `wakeAt` and `detail` and the seal its release wrote; after a planned stop, `paused` or `done` with the `detail` it
+     * set; after a crash, `running` with the dead holder and no new seal. On a fork's first open it is the record `fork`
+     * wrote: `paused`, generation 0, `detail.forkedFrom`. Null only when there was no `run.json` (a new run's first open).
+     */
+    readonly previous: RunRecord | null;
     readonly claim: RunClaim;
     /** The store the Harness was opened over, read-only: four reads on an object of their own, and no way to a write. */
     readonly storage: StoreReads;
@@ -156,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.
  */
@@ -171,6 +219,8 @@ export interface RunLease {
     readonly record: RunRecord;
     /** The seal the previous incarnation's clean release wrote; null on a first run and after a crash. */
     readonly sealedSeq: number | null;
+    /** `run.json` as the open found it, before it wrote this incarnation's: null when there was none (a new run's first open). */
+    readonly previous: RunRecord | null;
     readonly fenced: boolean;
     /**
      * The seal check on the app's store, before anything commits: the store's head (`storeHead`) below
@@ -272,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

@@ -278,6 +278,9 @@ class Lease {
     get sealedSeq() {
         return this.#previous?.sealedSeq ?? null;
     }
+    get previous() {
+        return this.#previous ?? null;
+    }
     get fenced() {
         return this.#fence !== undefined;
     }
@@ -308,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.
@@ -338,6 +344,25 @@ 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();
+                await seed({ root: claim.root, storePath: join(claim.store, STORE_FILE), workDir: claim.work });
+                await this.#dir.assertMounted();
+                await claim.barrier();
+            });
+        }
         await step("run.json", async () => {
             const now = new Date().toISOString();
             this.#noteBeat(await this.#write(() => ({
@@ -363,19 +388,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;
@@ -608,7 +635,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;
@@ -630,7 +657,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);
@@ -639,8 +666,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.
  */
@@ -694,6 +722,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;
@@ -702,7 +731,7 @@ class Run {
             // between the open and the hook, since the Harness has not resumed.
             await step("before-resume", async () => {
                 const head = (await storeHead(this.#store));
-                await before({ harness: this.#harness, context: this.#context, generation: lease.generation, record: lease.record, claim: lease.claim, storage: storeReads(storage), head });
+                await before({ harness: this.#harness, context: this.#context, generation: lease.generation, record: lease.record, previous: lease.previous, claim: lease.claim, storage: storeReads(storage), head });
             });
         }
         await step("resume", () => this.#harness.resume());
@@ -746,8 +775,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
@@ -755,25 +784,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

@@ -19,7 +19,7 @@ export type RunStatus = (typeof RUN_STATUSES)[number];
 export interface RunHolder {
     readonly driver: string;
     readonly host: string;
-    /** `/proc/sys/kernel/random/boot_id`; null where the platform has none. */
+    /** `/proc/sys/kernel/random/boot_id` (`kern.bootsessionuuid` on macOS); null where it cannot be read. */
     readonly bootId: string | null;
     readonly pid: number;
     /** When this incarnation claimed the run (ISO 8601). */
@@ -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.
@@ -81,12 +89,14 @@ export declare const ARCHIL_FSTYPE = "fuse.archil";
  * A run root held open as a directory for the life of the instance. `at` is `/proc/self/fd/<n>`, a path the kernel
  * resolves through the open directory and never through the root's path (Node has no openat; the magic link stands in
  * for it): a file made, written or renamed under `at` is in the directory opened at acquire, or the call fails (ENOTCONN
- * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away.
+ * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away. macOS has no
+ * such link: there `at` is the root's path (`byPath`), and only the checks below stand between a write and a root that was
+ * replaced.
  */
 export interface ClaimDir {
     /** The root's path, as the claim names it. */
     readonly root: string;
-    /** `/proc/self/fd/<n>`. Throws once closed: the number may then name another file. */
+    /** `/proc/self/fd/<n>`, or the root's path `byPath`. Throws once closed: the number may then name another file. */
     readonly at: string;
     /**
      * Resolves while the root's path still resolves to the directory held open (same device, same inode). A mount that was
@@ -107,6 +117,12 @@ export interface OpenClaimDirOptions {
     readonly fstype?: string | null;
     /** Default `/proc/self/mountinfo`. */
     readonly mountinfo?: string;
+    /**
+     * `at` is the root's path, not `/proc/self/fd/<n>`: the default on macOS, which has none. A write is checked against the
+     * held directory first (`assertMounted`), but a root renamed and replaced between that check and the write gets the
+     * write. For a local directory only.
+     */
+    readonly byPath?: boolean;
 }
 /** `major:minor` of a device number, as `/proc/self/mountinfo` writes it (glibc's encoding). */
 export declare function deviceName(dev: bigint): string;

package/dist/status.js

@@ -2,11 +2,12 @@
 // claim with write-to-temp, fsync, rename, and read by the supervisor (over the S3 API or a local mount). It is a hint
 // for the supervisor, never the source of truth: the store is. Any error writing it is a fence. The instance writes it
 // through its claim directory (`ClaimDir`), never by path, so a write cannot land under a mountpoint whose mount is gone.
-import { constants, readFileSync } from "node:fs";
+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 { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+import { thisBoot } from "./process-table.js";
 export const RUN_JSON = "run.json";
 /** The temporary file every write goes through; renamed over `run.json` once it is fsynced. */
 export const RUN_JSON_TEMP = "run.json.tmp";
@@ -95,6 +96,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.
@@ -204,7 +215,8 @@ export async function openClaimDir(root, options = {}) {
         await handle.close().catch(() => undefined);
         throw error instanceof FencedError ? error : unmounted(`checking the claim root ${root} failed: ${error.message}`, error);
     }
-    const at = `/proc/self/fd/${handle.fd}`;
+    const byPath = options.byPath ?? process.platform === "darwin";
+    const at = byPath ? root : `/proc/self/fd/${handle.fd}`;
     let closed = false;
     const same = (path, now, claims) => {
         if (now.dev === claims.dev && now.ino === claims.ino)
@@ -234,10 +246,18 @@ export async function openClaimDir(root, options = {}) {
         async assertSame(name) {
             if (closed)
                 throw unmounted(`the claim directory of ${root} is closed`);
-            const [byPath, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
+            if (byPath) {
+                // No second way to name the entry: the root must still be the directory held, and the entry on its device.
+                const [dir, entry] = await Promise.all([statOf(root), statOf(join(root, name))]);
+                same(root, dir, held);
+                if (entry.dev !== held.dev)
+                    throw unmounted(`${name} in the claim directory is on device ${deviceName(entry.dev)}, not the claim's ${deviceName(held.dev)}`);
+                return;
+            }
+            const [named, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
             if (inDir.dev !== held.dev)
                 throw unmounted(`${name} in the claim directory is on device ${deviceName(inDir.dev)}, not the claim's ${deviceName(held.dev)}`);
-            same(join(root, name), byPath, inDir);
+            same(join(root, name), named, inDir);
         },
         async close() {
             if (closed)
@@ -247,18 +267,10 @@ export async function openClaimDir(root, options = {}) {
         },
     };
 }
-function bootId() {
-    try {
-        return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * This process as a holder: the host driver's `handle` (default driver `local`, this machine's host name and boot id)
  * with this process's pid and `since`. A handle whose named fields have the wrong type is refused (RunRecordError).
  */
 export function currentHolder(handle = {}, since = new Date()) {
-    return holderOf({ driver: "local", host: hostname(), bootId: bootId(), ...handle, pid: process.pid, since: since.toISOString() });
+    return holderOf({ driver: "local", host: hostname(), bootId: thisBoot(), ...handle, pid: process.pid, since: since.toISOString() });
 }

package/dist/store.d.ts

@@ -39,8 +39,18 @@ export declare const PROFILE_PRAGMAS: {
         readonly mmap_size: 0;
     };
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export declare function assertPragmas(database: SqliteExecutor, profile: Profile): Promise<void>;
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export declare const FULLFSYNC_PRAGMAS: {
+    readonly fullfsync: 1;
+    readonly checkpoint_fullfsync: 1;
+};
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export declare function profilePragmas(profile: Profile, platform?: NodeJS.Platform): Readonly<Record<string, string | number>>;
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export declare function assertPragmas(database: SqliteExecutor, profile: Profile, platform?: NodeJS.Platform): Promise<void>;
 /**
  * The fenced state of one handle. The first error whose result code is in the I/O, full or not-a-database class marks it
  * fenced, runs `onFenced` once (before the error propagates), and from then on every operation fails with the same
@@ -84,6 +94,8 @@ export type OpenOptions = {
     readonly onFenced?: (error: StoreFencedError) => void;
     /** Wraps the raw database inside the fence, for instrumentation and fault injection. */
     readonly decorate?: (database: SqliteDatabase) => SqliteDatabase;
+    /** The platform whose pragmas the store takes (`profilePragmas`); default this one. For tests. */
+    readonly platform?: NodeJS.Platform;
 };
 export type ArchilStore = {
     readonly storage: SqliteStorage;