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

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) {
@@ -299,6 +310,11 @@ export function localHost(opts = {}) {
                 return;
             if (h.mode === "child") {
                 const pid = Number(h.pid);
+                // A handle comes back from run.json with whatever was written there, and stop signals its pid as a group: only a
+                // real process, then. A pid of 1 or below names a group (`kill(-0)` is this supervisor's own, `kill(-1)` every
+                // process it may signal), and without start ticks nothing tells a reused pid from the instance.
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
+                    return;
                 const alive = () => procStartTicks(pid) === h.startTicks;
                 if (!alive())
                     return;
@@ -333,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,15 +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 "./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,16 +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 "./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

@@ -3,5 +3,8 @@ export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim
 export * from "./errors.js";
 export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
 export type { ArchilStore, OpenOptions, PragmaMismatch, Profile } from "./store.js";
-export type { ArchilHost, Claim, RunRef } from "./claim.js";
-export type { RunHolder, RunRecord, RunStatus } from "./status.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

@@ -1,6 +1,8 @@
 // The narrow entry (`@parcha/pi-durable-disk/lease`) for a host that owns its own pi-durable Harness and store connections: the
 // claim's lifecycle without the supervisor, the host drivers, the CLI or the app contract. Importing it must not pull those
-// in (test/lease.test.ts bundles it and checks); a name added here is part of that promise.
+// in (test/lease-entry.test.ts bundles it and checks); a name added here is part of that promise.
 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.d.ts

@@ -0,0 +1,10 @@
+import type { AcquireOptions, Claim } from "./claim.js";
+import { type ClaimDir } from "./status.js";
+export interface LocalRun {
+    /** Takes the claim: the directory, made when it is missing. */
+    readonly acquire: (options: AcquireOptions) => Promise<Claim>;
+    /** Holds the directory open as the run's root; a local directory is not an Archil mount, so its type is not checked. */
+    readonly claimDir: (root: string) => Promise<ClaimDir>;
+}
+/** `openDurableRun`'s `acquire` and `claimDir` for a run in `root`, a directory on this machine. */
+export declare function localRun(root: string): LocalRun;

package/dist/local-run.js

@@ -0,0 +1,64 @@
+// A run on a plain local directory, for one machine: the claim is the directory itself. Nothing mounts and nothing is
+// delegated, so nothing but this machine's owner lock stands between two processes and the run: it is for a laptop, a CI
+// job or a test, never for a directory another machine can reach.
+//
+//   const run = await openDurableRun(ref, { ...localRun("/var/runs/run-1"), harness: { models, registry } });
+//
+// No mount token is needed (`acquire` is replaced). The claim's barrier does not sync the files the agent wrote: the
+// 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.
+//
+// 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";
+import { openClaimDir } from "./status.js";
+/** `openDurableRun`'s `acquire` and `claimDir` for a run in `root`, a directory on this machine. */
+export function localRun(root) {
+    const dir = resolve(root);
+    return {
+        acquire: async ({ ref }) => {
+            await mkdir(dir, { recursive: true });
+            return new LocalClaim(ref, dir);
+        },
+        claimDir: (at) => openClaimDir(at, { fstype: null }),
+    };
+}
+class LocalClaim {
+    ref;
+    disk;
+    root;
+    work;
+    store;
+    /** `<root>/commands`: a local run has no unit cgroup, so the next open ends the commands a killed one left running. */
+    commands;
+    reused = false;
+    stray = null;
+    forced = false;
+    timings = { mountMs: 0, verifyMs: 0 };
+    #fence;
+    constructor(ref, root) {
+        this.ref = ref;
+        this.disk = ref.disk;
+        this.root = root;
+        this.work = join(root, "work");
+        this.store = join(root, "store");
+        this.commands = join(root, "commands");
+    }
+    get fenced() {
+        return this.#fence !== undefined;
+    }
+    markFenced(cause) {
+        this.#fence ??= { cause };
+    }
+    async barrier() {
+        if (this.#fence)
+            throw new FencedError(`${this.root} is fenced; nothing is retried on it`, { cause: this.#fence.cause });
+        return { ms: 0 };
+    }
+    async release() {
+        return { via: "none" };
+    }
+}

package/dist/park.d.ts

@@ -26,9 +26,10 @@ export type BusyState = {
 };
 /**
  * The deadline of a task that is only sleeping: `until` in pi's retry phase (generation and compaction), `pollAt` in
- * its deferred poll phase. This is pi-durable 1.0.4's internal checkpoint shape (harness/generation.js, compaction.js),
- * read here and nowhere else. Any other shape is no deadline, which counts as busy, so a pi that changes the shape keeps
- * instances up rather than parking them mid-work. pi#10325 asks for this as a contract.
+ * its deferred poll phase. This is pi-durable's internal checkpoint shape, the same in 1.0.4 and 1.1.0
+ * (harness/generation.js, compaction.js), read here and nowhere else. Any other shape is no deadline, which counts as
+ * busy, so a pi that changes the shape keeps instances up rather than parking them mid-work. pi#10325 asks for this as
+ * a contract.
  */
 export declare function waitDeadline(checkpoint: JsonValue | undefined): number | undefined;
 /**

package/dist/park.js

@@ -27,9 +27,10 @@ export function leaseParkTarget(lease, harness, context = BACKGROUND_CONTEXT) {
 export const LOCAL_PARK_THRESHOLD_MS = 60_000;
 /**
  * The deadline of a task that is only sleeping: `until` in pi's retry phase (generation and compaction), `pollAt` in
- * its deferred poll phase. This is pi-durable 1.0.4's internal checkpoint shape (harness/generation.js, compaction.js),
- * read here and nowhere else. Any other shape is no deadline, which counts as busy, so a pi that changes the shape keeps
- * instances up rather than parking them mid-work. pi#10325 asks for this as a contract.
+ * its deferred poll phase. This is pi-durable's internal checkpoint shape, the same in 1.0.4 and 1.1.0
+ * (harness/generation.js, compaction.js), read here and nowhere else. Any other shape is no deadline, which counts as
+ * busy, so a pi that changes the shape keeps instances up rather than parking them mid-work. pi#10325 asks for this as
+ * a contract.
  */
 export function waitDeadline(checkpoint) {
     if (typeof checkpoint !== "object" || checkpoint === null || Array.isArray(checkpoint))

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;
+}