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

package/dist/hosts/daytona-launch.js

@@ -13,7 +13,7 @@
 // incarnation gets the token; a restart in place reads an empty stdin and reuses its live mount, as under localHost.
 // No cgroup per incarnation: commands a crashed instance detached can outlive it until the box is deleted.
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { procStartTicks, TERMINAL_EXITS } from "./local-host.js";
@@ -43,14 +43,17 @@ function writeState(path, state) {
 // Only a real process with its start ticks: `stop` signals these pids, the instance's as a group, and a pid of 1 or below
 // names a group (`kill(-1)` is every process this user may signal). The state file holds whatever was written there.
 const alive = (pid, ticks) => Number.isInteger(pid) && pid > 1 && typeof ticks === "number" && procStartTicks(pid) === ticks;
-/** running while either process lives; otherwise stopped after a clean exit, failed after any other end. */
+/** running while either process lives and the launcher has not recorded its exit; otherwise stopped after a clean exit,
+ * failed after any other end. Every "exited" the launcher saves is final and comes after its instance ended, so once it is
+ * saved (and no instance lives) the record is the answer, even while the launcher's own process is still exiting. */
 export function launchStatus(dir, name) {
     const state = readState(dir, name);
     if (!state)
         return { status: "failed", state: null, launcherAlive: false, instanceAlive: false };
     const launcherAlive = alive(state.launcher, state.launcherTicks);
     const instanceAlive = alive(state.instance, state.instanceTicks);
-    if (launcherAlive || instanceAlive)
+    const ended = state.phase === "exited" && !instanceAlive;
+    if (!ended && (launcherAlive || instanceAlive))
         return { status: "running", state, launcherAlive, instanceAlive };
     const clean = state.phase === "exited" && state.exit === 0;
     return { status: clean ? "stopped" : "failed", state, launcherAlive, instanceAlive };
@@ -216,8 +219,12 @@ export async function stop(dir, name, timeoutMs) {
         }
     };
     let s = launchStatus(dir, name);
-    if (s.status !== "running")
+    if (s.status !== "running") {
+        // The launcher recorded its exit and is ending on its own; a launcher process that outstays its record is still sent away.
+        if (s.launcherAlive)
+            kill(s.state.launcher, s.state.launcherTicks, "SIGTERM");
         return s;
+    }
     if (s.launcherAlive)
         kill(s.state.launcher, s.state.launcherTicks, "SIGTERM");
     else
@@ -262,7 +269,22 @@ async function main(argv) {
             return 2;
     }
 }
-if (process.argv[1] && resolve(process.argv[1]) === LAUNCH_SCRIPT) {
+/**
+ * Whether Node was started with this module. LAUNCH_SCRIPT comes from import.meta.url, which is the real path; argv[1] is
+ * the path as given, which may go through a link (a symlinked package directory, pnpm's linked node_modules).
+ */
+function invokedAsMain() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return realpathSync(arg) === LAUNCH_SCRIPT;
+    }
+    catch {
+        return resolve(arg) === LAUNCH_SCRIPT;
+    }
+}
+if (invokedAsMain()) {
     main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
         process.stderr.write(`${err.message}\n`);
         process.exit(1);

package/dist/hosts/daytona.js

@@ -121,7 +121,11 @@ export class DaytonaHostError extends PdaError {
         super(code, message, options);
     }
 }
-const BOX_PATH = /^\/[A-Za-z0-9._/-]+$/;
+// Shell-inert characters only: the paths go into launcher command lines. `@` admits npm's scoped package directories
+// (`node_modules/@scope/pkg`), where the package is installed with npm and not copied to a fixed directory.
+const BOX_PATH = /^\/[A-Za-z0-9._@/-]+$/;
+/** A path that climbs out of where it names: never a box path, whatever else is in it. */
+const climbs = (path) => path.split("/").includes("..");
 const ACCOUNT = /^(?:[a-z_][a-z0-9_-]{0,31}|\d{1,10})$/;
 const FLEET = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const UP = new Set(["creating", "pulling_snapshot", "pending_build", "building_snapshot", "starting", "restoring", "resuming", "resizing", "snapshotting", "forking", "stopping", "pausing", "paused"]);
@@ -152,6 +156,14 @@ export function sandboxName(prefix, runId, now) {
     return `${prefix}${slug}-${stamp}`.slice(0, 63);
 }
 /** The last line of a command's output that parses as JSON, or null. */
+/**
+ * What the launcher printed, for a start it gave no reason for: the last 4 KB, or that it printed nothing. It prints only
+ * its state; the mount token is in a root-only file it reads, never in its output.
+ */
+function launcherOutput(text) {
+    const out = text.trim();
+    return out ? `the launcher printed: ${out.slice(-4096)}` : "the launcher printed nothing and exited 0";
+}
 function lastJson(text) {
     for (const line of text.trim().split("\n").reverse()) {
         try {
@@ -185,7 +197,7 @@ export function daytonaHost(opts) {
     const now = opts.now ?? Date.now;
     const launch = opts.launcher ?? `${packageDir}/dist/hosts/daytona-launch.js`;
     for (const [what, value] of Object.entries({ mountRoot, node, packageDir, archil, boxDir: dir, stageDir: stage, launcher: launch })) {
-        if (!BOX_PATH.test(value))
+        if (!BOX_PATH.test(value) || climbs(value))
             throw new DaytonaHostError("INVALID_ARGUMENT", `${what} ${JSON.stringify(value)} is not a plain absolute path`);
     }
     if (!ACCOUNT.test(user) || !ACCOUNT.test(group))
@@ -288,7 +300,7 @@ export function daytonaHost(opts) {
                 const r = await run(box, launcher("start", name, left), Math.ceil(left / 1000) + 10, "starting the instance");
                 const state = lastJson(r.result);
                 if (!state || !(state.spawned > 0)) {
-                    throw new DaytonaHostError("START_FAILED", `the instance in ${name} did not start: ${state?.reason ?? r.result.trim().slice(0, 300)}`);
+                    throw new DaytonaHostError("START_FAILED", `the instance in ${name} did not start: ${state?.reason || launcherOutput(r.result)}`);
                 }
                 return handle;
             }

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

@@ -54,10 +54,13 @@ export declare class LocalHostError extends PdaError {
         cause?: unknown;
     });
 }
+/** The argv of that child for `path`. */
+export declare const statCodeArgv: (path: string) => string[];
 /** Exits a restart cannot fix: 65 data error, 70 store head unreadable, 75 fenced, 76 held. */
 export declare const TERMINAL_EXITS: readonly [65, 70, 75, 76];
 /** Minimal environment, a timeout that settles even if a grandchild keeps the pipes, and the input on stdin. */
 export declare const runCommand: Runner;
+/** This boot's id: `/proc/sys/kernel/random/boot_id`, or `kern.bootsessionuuid` on macOS. Throws when it cannot be read. */
 export declare function currentBootId(): string;
 /** `systemctl show` output as a map. */
 export declare function parseShow(text: string): Record<string, string>;
@@ -67,5 +70,8 @@ export declare function localHost(opts?: LocalHostOptions): HostDriver & {
     readonly hostName: string;
     readonly mountRoot: string;
 };
-/** Field 22 of /proc/<pid>/stat (start time in clock ticks), so a reused pid is never mistaken for the instance. */
+/**
+ * A live process's start (field 22 of /proc/<pid>/stat, in clock ticks; on macOS the second it started), so a reused pid is
+ * never mistaken for the instance. Null for a zombie, a process that is gone, or one the table cannot be read for.
+ */
 export declare function procStartTicks(pid: number): number | null;

package/dist/hosts/local-host.js

@@ -12,14 +12,14 @@
 // place reads nothing and reuses its live mount), the instance closes its stdin after reading, and stop removes it.
 // The token is never in argv, the environment, a systemd credential directory or anything the run's user can open.
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import { extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ARCHIL_SCOPED, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
+import { ARCHIL_SCOPED, DEAD_CONNECTION, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
 import { EXIT_FENCED, EXIT_HELD, PdaError } from "../errors.js";
 import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
+import { processTable, thisBoot } from "../process-table.js";
 export class LocalHostError extends PdaError {
     constructor(code, message, options = {}) {
         super(code, message, options);
@@ -32,7 +32,13 @@ const SYSTEMD_RUN = "/usr/bin/systemd-run";
 const ARCHIL = "/usr/bin/archil";
 const UNIT_SAFE = /^[A-Za-z0-9:_.-]{1,200}$/;
 const POLITE_UNMOUNT_MS = 10_000;
-const STAT = "/usr/bin/stat";
+/**
+ * A stat of one path in a child process, so a stuck daemon never blocks this one: prints the errno code (or "ok"), never a
+ * message, which coreutils' `stat` prints in the locale's language.
+ */
+const STAT_CODE = `try { require("node:fs").statSync(process.argv[1]); process.stdout.write("ok"); } catch (e) { process.stdout.write(String(e.code)); process.exitCode = 1; }`;
+/** The argv of that child for `path`. */
+export const statCodeArgv = (path) => [process.execPath, "-e", STAT_CODE, path];
 const FUSERMOUNT = "/usr/bin/fusermount";
 const UMOUNT = "/usr/bin/umount";
 /** How long a stat of the mountpoint may take before its daemon counts as alive but stuck (never removed). */
@@ -63,8 +69,12 @@ export const runCommand = (argv, opts = {}) => new Promise((resolve, reject) =>
     child.stdin.on("error", () => { });
     child.stdin.end(opts.input ?? "");
 });
+/** This boot's id: `/proc/sys/kernel/random/boot_id`, or `kern.bootsessionuuid` on macOS. Throws when it cannot be read. */
 export function currentBootId() {
-    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const boot = thisBoot();
+    if (boot === null)
+        throw new Error("this machine's boot id cannot be read");
+    return boot;
 }
 const firstLine = (r) => (r.stderr.trim().split("\n").at(-1) ?? "").slice(0, 300);
 const okRan = (r) => r.code === 0 && !r.timedOut;
@@ -234,13 +244,14 @@ export function localHost(opts = {}) {
             await new Promise((r) => setTimeout(r, 100));
     }
     /**
-     * Whether the mount at `mp` is dead: its FUSE daemon is gone, so the kernel answers with ENOTCONN ("Transport endpoint
-     * is not connected"). The stat runs in a child with a timeout, so a live but stuck daemon never blocks this process; a
-     * stat that answers or does not finish is a live mount.
+     * Whether the mount at `mp` is dead: its FUSE daemon is gone, so the stat fails with one of `DEAD_CONNECTION`'s codes
+     * (ENOTCONN, or ECONNABORTED for a stat in flight while the dying daemon's connection is torn down). The stat runs in a
+     * child with a timeout, so a live but stuck daemon never blocks this process, and the child prints the code, not a
+     * message; a stat that answers, fails otherwise or does not finish is a live mount.
      */
     async function deadMount(mp) {
-        const r = await exec([STAT, "-c", "%i", mp], { timeoutMs: STAT_TIMEOUT_MS });
-        return !r.timedOut && r.code !== 0 && /Transport endpoint is not connected/.test(r.stderr);
+        const r = await exec(statCodeArgv(mp), { timeoutMs: STAT_TIMEOUT_MS });
+        return !r.timedOut && r.code !== 0 && DEAD_CONNECTION.has(r.stdout.trim());
     }
     /** Remove a dead mount: `fusermount -u`, then a lazy `umount -l`. The mount table, not an exit code, decides. */
     async function removeDeadMount(mp) {
@@ -338,19 +349,17 @@ export function localHost(opts = {}) {
         },
     };
 }
-/** Field 22 of /proc/<pid>/stat (start time in clock ticks), so a reused pid is never mistaken for the instance. */
+/**
+ * A live process's start (field 22 of /proc/<pid>/stat, in clock ticks; on macOS the second it started), so a reused pid is
+ * never mistaken for the instance. Null for a zombie, a process that is gone, or one the table cannot be read for.
+ */
 export function procStartTicks(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
         return null;
-    let stat;
     try {
-        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        return processTable().snapshot().info(pid)?.start ?? null;
     }
     catch {
         return null;
     }
-    const rest = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
-    if (rest[0] === "Z" || rest[0] === "X")
-        return null;
-    return Number(rest[19]);
 }

package/dist/index.d.ts

@@ -1,16 +1,31 @@
-export * from "./app.js";
-export * from "./claim.js";
-export { PathOutsideWorkError, type RefusalReason } from "./confine.js";
-export * from "./env.js";
-export * from "./errors.js";
-export * from "./fork.js";
-export * from "./hosts/daytona.js";
-export * from "./hosts/docker.js";
-export * from "./hosts/local-host.js";
-export * from "./local-run.js";
-export * from "./park.js";
-export * from "./run.js";
-export * from "./serve.js";
-export * from "./status.js";
-export * from "./store.js";
-export * from "./supervise.js";
+export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
+export type { BeforeResume, DurableRun, LeaseOptions, OpenDurableRunOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunEnv, RunErrorCode, RunLease, StoreHeadSource, StoreReads } from "./run.js";
+export { localRun } from "./local-run.js";
+export type { LocalRun } from "./local-run.js";
+export { CLAIM_UNMOUNTED, openClaimDir, RunRecordError } from "./status.js";
+export type { ClaimDir, OpenClaimDirOptions, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";
+export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
+export type { ArchilEnvClaim, ArchilEnvFactory, ArchilEnvOptions, EnvErrorCode } from "./env.js";
+export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
+export type { AcquireOptions, ArchilHost, Claim, ControlApi, PathlessResolver, RunRef, Unmounted } from "./claim.js";
+export { PathOutsideWorkError } from "./confine.js";
+export type { RefusalReason } from "./confine.js";
+export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
+export type { ClaimErrorCode, Holder } from "./errors.js";
+export type { ArchilStore, Fence, FencedDatabase, Profile, StoreFencedError } from "./store.js";
+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 { 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 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 { 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";
+export type { ForkErrorCode, ForkLocalResult, ForkOptions, ForkResult } from "./fork.js";

package/dist/index.js

@@ -1,17 +1,24 @@
-// Public API.
-export * from "./app.js";
-export * from "./claim.js";
+// The package's public API. Every name is listed: a new export is a reviewed line here, and test/entries.test.ts pins the
+// list of each entry. `./lease` is the narrow entry for a host that owns its Harness; `./internals` holds plumbing that
+// examples and demos use, with no compatibility promise.
+// The run: open it, on a disk or a local directory, with its environment, its claim and the errors it fails with.
+export { openDurableRun, RunError, StoreBehindSealError } from "./run.js";
+export { localRun } from "./local-run.js";
+export { CLAIM_UNMOUNTED, openClaimDir, RunRecordError } from "./status.js";
+export { ArchilCodingTools, archilEnv, EnvClosedError, EnvError, markReadOnlySafe } from "./env.js";
+export { acquire, ARCHIL_SCOPED, revoke, takeOver } from "./claim.js";
 export { PathOutsideWorkError } from "./confine.js";
-export * from "./env.js";
-export * from "./errors.js";
-export * from "./fork.js";
-export * from "./hosts/daytona.js";
-export * from "./hosts/docker.js";
-export * from "./hosts/local-host.js";
-export * from "./local-run.js";
-export * from "./park.js";
-export * from "./run.js";
-export * from "./serve.js";
-export * from "./status.js";
-export * from "./store.js";
-export * from "./supervise.js";
+export { ClaimError, FencedError, HeldError, PdaError } from "./errors.js";
+// The app contract: what `--app` names.
+export { AppError } from "./app.js";
+// The supervisor and the host drivers.
+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";
+// Serve: one HTTP request runs one turn.
+export { requestRun, ServeConfigError, ServeError, serveRun } from "./serve.js";
+// Parking: an idle run gives its host back.
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
+// Fork: a new run from a run's committed state.
+export { fork, ForkError, forkLocal } from "./fork.js";

package/dist/internals.d.ts

@@ -0,0 +1,3 @@
+export { createRunDir, findDelegations, mintMountToken, pathlessResolver, removeMountToken, runPath, unmountClaim } from "./claim.js";
+export { LABEL_FLEET, LABEL_RUN, sandboxName, sandboxStatus, sweepSandboxes } from "./hosts/daytona.js";
+export { isLeaseFresh, parseRunRecord, RUN_JSON } from "./status.js";

package/dist/internals.js

@@ -0,0 +1,6 @@
+// `@parcha/pi-durable-disk/internals`: the claim, status and Daytona plumbing that this repository's examples and demos
+// use. No compatibility promise: a name here may change or go in any release, and the CHANGELOG says when. A name moves
+// to the root entry when something outside this repository needs it.
+export { createRunDir, findDelegations, mintMountToken, pathlessResolver, removeMountToken, runPath, unmountClaim } from "./claim.js";
+export { LABEL_FLEET, LABEL_RUN, sandboxName, sandboxStatus, sweepSandboxes } from "./hosts/daytona.js";
+export { isLeaseFresh, parseRunRecord, RUN_JSON } from "./status.js";

package/dist/lease.d.ts

@@ -5,3 +5,6 @@ export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS,
 export type { ArchilStore, OpenOptions, PragmaMismatch, Profile } from "./store.js";
 export type { AcquireOptions, ArchilHost, Claim, RunRef, Unmounted } from "./claim.js";
 export type { ClaimDir, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
+export type { BusyState, DrainOptions, Parking, ParkOptions, ParkResult, ParkTarget } from "./park.js";
+export type { DurableRun, RunEnv } from "./run.js";

package/dist/lease.js

@@ -4,3 +4,5 @@
 export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
 export * from "./errors.js";
 export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
+// Parking, for a Harness the host opened over `openRunLease` (`leaseParkTarget`).
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";

package/dist/local-run.js

@@ -8,8 +8,9 @@
 // store's own commits are made durable by SQLite, and work/ is the operating system's to flush; a power loss can lose what
 // it had not written yet. It refuses once the claim is fenced, as a mount's does.
 //
-// Linux only, for now: the run's root is held open through /proc/self/fd (openClaimDir), and the default environment
-// (`archilEnv`) confines commands with `setpriv` (util-linux) and the file tools through /proc/self/fd. macOS has neither.
+// On macOS, for development: it has no /proc/self/fd and no setpriv, so there the run's root is addressed by its path
+// (openClaimDir's `byPath`), commands keep the user's rights, the file tools are confined by path (confine.ts), and the
+// commands are recorded from ps (process-table.ts). The README's "On macOS" says what that costs.
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { FencedError } from "./errors.js";

package/dist/process-table.d.ts

@@ -0,0 +1,38 @@
+/** A live process (a zombie is not one): its parent, its group, and its start. */
+export interface ProcessInfo {
+    readonly ppid: number;
+    readonly pgrp: number;
+    readonly start: number;
+}
+/** One look at the processes. Through ps, every `info` and `children` of one snapshot sees the same listing; /proc is read live. */
+export interface ProcessSnapshot {
+    info(pid: number): ProcessInfo | undefined;
+    /** The direct children of `pid`. */
+    children(pid: number): number[];
+    /** Whether `pid` was started with `name=value` in its environment (false when it cannot be read). */
+    marked(pid: number, name: string, value: string): boolean;
+    /** Its command line, for a message; `?` when it cannot be read. */
+    commandLine(pid: number): string;
+}
+export interface ProcessTable {
+    /** A new look. Through ps it throws when the listing cannot be had or read: no process is ever taken for gone on a failed read. */
+    snapshot(): ProcessSnapshot;
+    /** This boot's id; undefined when it cannot be read. */
+    bootId(): string | undefined;
+    /** How often a recorder's walk is worth repeating: a /proc read is cheap, a ps listing is not. */
+    readonly walkMs: number;
+}
+/** The table on Linux: `/proc` (or another directory laid out like it, for tests). */
+export declare function procTable(proc?: string): ProcessTable;
+/** Runs a program with arguments and returns what it printed; throws when it fails. */
+export type CommandRunner = (file: string, args: readonly string[]) => string;
+/** The table on macOS: `ps` and `sysctl`, through `run` (for tests). */
+export declare function psTable(run?: CommandRunner): ProcessTable;
+/** Test seam: a table that stands in for this machine's everywhere `processTable()` is read. */
+export declare const processTableHooks: {
+    table?: ProcessTable;
+};
+/** This machine's table: ps on macOS, /proc elsewhere. */
+export declare function processTable(): ProcessTable;
+/** This boot's id on this machine, null when it cannot be read. */
+export declare function thisBoot(): string | null;

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

@@ -130,7 +130,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;
@@ -171,6 +179,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

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;
     }
@@ -702,7 +705,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());