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

package/dist/cli.js

@@ -9,7 +9,7 @@
 // The API key is read from the environment variable named by `--api-key-env` (default ARCHIL_API_KEY) and only by the
 // supervisor commands; `run` never needs it and a host driver never passes it on.
 import { closeSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { ARCHIL_SCOPED, DEFAULT_MOUNT_ROOT, runPath, TOKEN_PREFIX, unmountClaim } from "./claim.js";
@@ -19,8 +19,11 @@ import { fork } from "./fork.js";
 import { drain, recordWake, watchParking } from "./park.js";
 import { isLoopback, readServeToken, serveRun } from "./serve.js";
 import { dockerHost } from "./hosts/docker.js";
-import { localHost } from "./hosts/local-host.js";
-import { checkHost, CONTROL_TIMEOUT_MS, readRunStatus, superviseRuns, sweepTokens, withTimeouts, } from "./supervise.js";
+import { localHost, procStartTicks } from "./hosts/local-host.js";
+import { processTable, thisBoot } from "./process-table.js";
+import { localRun } from "./local-run.js";
+import { parseRunRecord, RUN_JSON } from "./status.js";
+import { archilControl, checkHost, CONTROL_TIMEOUT_MS, readRunStatus, superviseRuns, sweepTokens, withTimeouts, } from "./supervise.js";
 import { openDurableRun } from "./run.js";
 import { AppError, loadApp } from "./app.js";
 class UsageError extends PdaError {
@@ -29,6 +32,7 @@ class UsageError extends PdaError {
     }
 }
 const USAGE = `usage:
+  pi-durable-disk run --dir PATH --app MODULE [--id ID] [any run flag below but the Archil ones]
   pi-durable-disk run --disk D --region R --id ID --app MODULE [--mount-root DIR] [--archil BIN]
                         [--heartbeat-ms N] [--lease-expiry-ms N] [--lease-margin-ms N] [--on-sigterm resume|pause]
                         [--token-stdin] [--run-as USER] [--serve PORT] [--serve-host H] [--serve-url URL]
@@ -42,6 +46,7 @@ const USAGE = `usage:
                         with --host docker: --image IMAGE [--app-root DIR] [--fleet F] [--name-prefix P] [--run-as USER]
                         [--docker-arg ARG ...] [--apparmor auto|PROFILE|none] [--docker BIN]
   pi-durable-disk supervise --check --disk D --region R [--mount-root DIR] [--user U] [--group G] [--check-id-prefix P]
+  pi-durable-disk status --dir PATH
   pi-durable-disk status --disk D --region R --id ID [--host-name NAME] [--api-key-env NAME] [--docker BIN]
   pi-durable-disk release --id ID [--mount-root DIR]
   pi-durable-disk fork --disk D --region R --id ID --new-id NEW [--mount-root DIR] [--archil BIN] [--token-prefix P]
@@ -141,29 +146,16 @@ const need = (v, ...keys) => {
 };
 const str = (v, fallback) => (typeof v === "string" ? v : fallback);
 const emit = (line) => process.stdout.write(`${JSON.stringify({ at: new Date().toISOString(), ...line })}\n`);
-/** The disk's control API for the supervisor, plus the two lists only the disk record carries (users, clients). */
-async function control(values) {
+/**
+ * The disk's control API for the supervisor (`archilControl`), from the API key in `--api-key-env` (default
+ * ARCHIL_API_KEY) and `--disk` and `--region`. `client` replaces the `disk` client (tests).
+ */
+export async function cliControl(values, client) {
     const name = str(values["api-key-env"], "ARCHIL_API_KEY");
     const apiKey = process.env[name];
     if (!apiKey)
         throw new UsageError(`no API key in $${name}`);
-    const { configure, getDisk } = await import("disk");
-    configure({ apiKey, region: str(values.region) });
-    const id = str(values.disk);
-    const disk = await getDisk(id);
-    return {
-        getObject: (key) => disk.getObject(key),
-        headObject: (key) => disk.headObject(key),
-        putObject: (key, body, options) => disk.putObject(key, body, options),
-        addUser: (user) => disk.addUser(user),
-        removeUser: (type, identifier) => disk.removeUser(type, identifier),
-        listDelegations: () => disk.listDelegations(),
-        revokeDelegation: (d) => disk.revokeDelegation(d),
-        exec: (command) => disk.exec(command),
-        listObjects: (prefix, options) => disk.listObjects(prefix, options),
-        deleteObjects: (keys, options) => disk.deleteObjects(keys, options),
-        listUsers: async () => (await getDisk(id)).authorizedUsers ?? [],
-    };
+    return archilControl({ apiKey, disk: str(values.disk), region: str(values.region), ...(client ? { client } : {}) });
 }
 // ---- run ---------------------------------------------------------------------------------------------------------------
 /**
@@ -201,8 +193,12 @@ async function readToken(values) {
  * between the open and the exit is `serveUntilDone`.
  */
 async function runInstance(values) {
-    need(values, "disk", "region", "id", "app");
-    const ref = { disk: str(values.disk), region: str(values.region), id: str(values.id) };
+    const dir = localDir(values, ["disk", "region", "mount-root", "archil", "token-stdin"]);
+    if (dir === undefined)
+        need(values, "disk", "region", "id", "app");
+    else
+        need(values, "app");
+    const ref = dir === undefined ? { disk: str(values.disk), region: str(values.region), id: str(values.id) } : { disk: "local", region: "local", id: str(values.id) ?? basename(dir) };
     const runAs = typeof values["run-as"] === "string" ? runUser(values["run-as"]) : undefined;
     if (runAs && process.getuid?.() !== 0)
         throw new UsageError("--run-as needs an instance that runs as root (inside a container); elsewhere run the instance as the run user");
@@ -222,7 +218,7 @@ async function runInstance(values) {
         throw new UsageError(`--serve-host ${serveHost} is not loopback: name a --serve-token-file`);
     const serveToken = tokenFile === undefined ? undefined : readServeToken(tokenFile);
     const mountRoot = str(values["mount-root"], DEFAULT_MOUNT_ROOT);
-    const root = join(mountRoot, runPath(ref.id));
+    const root = dir ?? join(mountRoot, runPath(ref.id));
     const log = (event, extra = {}) => process.stderr.write(`${JSON.stringify({ at: new Date().toISOString(), event, run: ref.id, ...extra })}\n`);
     let app;
     try {
@@ -234,6 +230,10 @@ async function runInstance(values) {
     }
     const { onOpen, beforeResume, root: rootOptions, wake: appWake, ...harness } = app;
     const holder = JSON.parse(process.env.PDA_HOLDER ?? "{}");
+    // On a local directory nothing else knows this instance: its start ticks go into the holder, so `status --dir` tells it
+    // from a later process that reuses its pid (a driver's handle already carries them).
+    if (dir !== undefined && typeof holder.startTicks !== "number")
+        holder.startTicks = procStartTicks(process.pid);
     const cgroup = watchdogOwnsCgroup(holder);
     if (cgroup.warning)
         log("cgroup not owned", { warning: cgroup.warning });
@@ -250,9 +250,8 @@ async function runInstance(values) {
     let run;
     try {
         run = await openDurableRun(ref, {
-            mountToken: await readToken(values),
-            mountRoot,
-            host: { archil: str(values.archil) },
+            // A local directory is its own claim (no mount, no token); a disk's run is mounted with a token.
+            ...(dir === undefined ? { mountToken: await readToken(values), mountRoot, host: { archil: str(values.archil) } } : localRun(dir)),
             harness,
             ...(runAs
                 ? { env: (c) => archilEnv(c, { runAs: { uid: runAs.uid, gid: runAs.gid }, shellEnv: { HOME: runAs.home, USER: runAs.name, LOGNAME: runAs.name } }) }
@@ -451,7 +450,7 @@ async function supervise(values) {
         throw new UsageError("--check proves this host's own mounts; with --host docker the containers mount, so it does not apply");
     if (docker && (typeof values.image !== "string" || !values.image))
         throw new UsageError("--host docker needs --image");
-    const disk = await control(values);
+    const disk = await cliControl(values);
     const controlTimeoutMs = values["control-timeout"] ? parseDuration(str(values["control-timeout"])) : CONTROL_TIMEOUT_MS;
     if (values.check) {
         const report = await checkHost({
@@ -537,8 +536,11 @@ async function supervise(values) {
     return 0;
 }
 async function status(values) {
+    const dir = localDir(values, ["disk", "region", "mount-root", "api-key-env", "host-name", "docker"]);
+    if (dir !== undefined)
+        return localStatus(dir);
     need(values, "disk", "region", "id");
-    const disk = await control(values);
+    const disk = await cliControl(values);
     const id = str(values.id);
     const run = await readRunStatus(disk, id);
     const { findDelegations } = await import("./claim.js");
@@ -556,6 +558,67 @@ async function status(values) {
     emit({ run: id, runJson: run, delegations: delegations.map(({ clientId, inodeId, path, isOrphaned, isPending }) => ({ clientId, inodeId, path, isOrphaned, isPending })), holderStatus, ...(container ? { container } : {}) });
     return 0;
 }
+/**
+ * `--dir PATH`: the run is the local directory PATH (`localRun`), so the Archil flags mean nothing and are refused. Returns
+ * the directory, absolute; undefined without `--dir`.
+ */
+function localDir(values, archilFlags) {
+    if (values.dir === undefined)
+        return undefined;
+    const dir = str(values.dir);
+    if (!dir)
+        throw new UsageError("--dir needs a path");
+    const mixed = archilFlags.filter((flag) => values[flag] !== undefined);
+    if (mixed.length > 0)
+        throw new UsageError(`--dir is a run on a local directory: it takes no ${mixed.map((flag) => `--${flag}`).join(", ")}`);
+    return resolve(dir);
+}
+/**
+ * `status --dir PATH`: `run.json` read from the directory, and whether its holder is still the process that claimed it:
+ * `running` when it is this boot's and its pid is alive with the start ticks the holder recorded (a later process that
+ * reuses the pid has others), `stopped` when it is not, `gone` from another boot, and `unknown` when the holder recorded no
+ * start ticks (a run opened by a library caller) and its pid is alive.
+ */
+function localStatus(dir) {
+    let text;
+    try {
+        text = readFileSync(join(dir, RUN_JSON), "utf8");
+    }
+    catch (err) {
+        throw new UsageError(`no run in ${dir}: ${err.message}`);
+    }
+    const run = parseRunRecord(text);
+    let holderStatus = null;
+    const holder = run.holder;
+    if (holder) {
+        // A read that failed (sysctl or ps on macOS) is no exit: it says `unknown`, never `gone` or `stopped`.
+        const boot = thisBoot();
+        const ticks = startOf(Number(holder.pid));
+        if (boot === null)
+            holderStatus = "unknown";
+        else if (holder.bootId !== boot)
+            holderStatus = "gone";
+        else if (ticks === undefined)
+            holderStatus = "unknown";
+        else if (typeof holder.startTicks === "number")
+            holderStatus = ticks === holder.startTicks ? "running" : "stopped";
+        else
+            holderStatus = ticks === null ? "stopped" : "unknown";
+    }
+    emit({ run: run.run, dir, runJson: run, holderStatus });
+    return 0;
+}
+/** A live process's start (null: no such process, or a zombie), or undefined when the process table cannot be read. */
+function startOf(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return null;
+    try {
+        return processTable().snapshot().info(pid)?.start ?? null;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function release(values) {
     need(values, "id");
     const via = await unmountClaim(join(str(values["mount-root"], DEFAULT_MOUNT_ROOT), runPath(str(values.id))));
@@ -564,7 +627,7 @@ async function release(values) {
 }
 async function forkRun(values) {
     need(values, "disk", "region", "id", "new-id");
-    const disk = await control(values);
+    const disk = await cliControl(values);
     const result = await fork({ disk: str(values.disk), region: str(values.region), id: str(values.id) }, str(values["new-id"]), {
         control: disk,
         mountRoot: str(values["mount-root"], DEFAULT_MOUNT_ROOT),
@@ -583,6 +646,7 @@ export async function main(argv) {
             case "run":
                 return await runInstance(parse(rest, {
                     ...COMMON,
+                    dir: { type: "string" },
                     archil: { type: "string" },
                     app: { type: "string" },
                     "heartbeat-ms": { type: "string" },
@@ -641,7 +705,7 @@ export async function main(argv) {
                     apparmor: { type: "string" },
                 }));
             case "status":
-                return await status(parse(rest, { ...COMMON, docker: { type: "string" } }));
+                return await status(parse(rest, { ...COMMON, dir: { type: "string" }, docker: { type: "string" } }));
             case "release":
                 return await release(parse(rest, COMMON));
             case "fork":

package/dist/commands.d.ts

@@ -1,6 +1,7 @@
+import { type ProcessTable } from "./process-table.js";
 /** The environment variable that marks a command as one environment's: its value is that recorder's token. */
 export declare const COMMANDS_MARK = "PI_DURABLE_DISK_COMMANDS";
-/** One process, as recorded: a pid alone could be reused, a pid with its start ticks on one boot cannot. */
+/** One process, as recorded: a pid alone could be reused, a pid with its start on one boot cannot (process-table.ts). */
 export interface ProcessMark {
     readonly pid: number;
     readonly start: number;
@@ -19,6 +20,8 @@ export interface Reaped {
 export interface CommandsOptions {
     /** The `/proc` to read; for tests. */
     readonly proc?: string;
+    /** The process table to read; default this machine's (`/proc`, or `proc` when given; ps on macOS). For tests. */
+    readonly table?: ProcessTable;
     /** How a reap signals; default `process.kill`. For tests. */
     readonly kill?: (target: number, signal: NodeJS.Signals) => void;
 }

package/dist/commands.js

@@ -1,81 +1,26 @@
 // The commands a run's environment starts, recorded where the next open of the same claim finds them. pi makes each
 // command the leader of a process group of its own, so killing an instance does not reach its commands: a host's unit
 // cgroup or a container ends them with it, and a run on a local directory has neither. While commands run, the instance
-// walks its own process tree (`/proc/<pid>/task/<tid>/children`) and records each of its commands' group leader and every
-// descendant it has seen, each by pid, start ticks and boot. Its commands are the children that lead their own group and
-// carry its mark (COMMANDS_MARK=<its token>) in their environment: another environment's commands in the same process,
-// or the app's own helpers, are not its to record. The next open, which holds the owner lock, kills whatever a
-// previous incarnation recorded that is still the same process (pid, start ticks and boot all match), waits until it is
-// gone, and clears the records, before the Harness opens. Only the instance writes records: a command never does.
-// Nothing stops a command from writing one too, and none needs stopping: a run's commands run as the instance's user (or,
-// with `runAs`, as another one that cannot write the instance's 0700 directory), so a record a command forged names only
-// what that command could already kill itself. A record grants nothing.
+// walks its own process tree (`/proc/<pid>/task/<tid>/children` on Linux, one ps listing on macOS: process-table.ts) and
+// records each of its commands' group leader and every descendant it has seen, each by pid, start and boot. Its commands
+// are the children that lead their own group and carry its mark (COMMANDS_MARK=<its token>) in their environment:
+// another environment's commands in the same process, or the app's own helpers, are not its to record. The next open,
+// which holds the owner lock, kills whatever a previous incarnation recorded that is still the same process (pid, start
+// and boot all match), waits until it is gone, and clears the records, before the Harness opens. Only the instance writes
+// records: a command never does. Nothing stops a command from writing one too, and none needs stopping: a run's commands
+// run as the instance's user (or, with `runAs`, as another one that cannot write the instance's 0700 directory), so a
+// record a command forged names only what that command could already kill itself. A record grants nothing.
 import { randomUUID } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { HeldError } from "./errors.js";
+import { processTable, procTable } from "./process-table.js";
 /** The environment variable that marks a command as one environment's: its value is that recorder's token. */
 export const COMMANDS_MARK = "PI_DURABLE_DISK_COMMANDS";
-/** `/proc/<pid>/stat`: fields after the last `)` (the command name may hold spaces and parentheses); a zombie is gone. */
-function stat(proc, pid) {
-    try {
-        const text = readFileSync(join(proc, String(pid), "stat"), "utf8");
-        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;
-    }
-}
-function bootId(proc) {
-    try {
-        return readFileSync(join(proc, "sys/kernel/random/boot_id"), "utf8").trim() || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** The direct children of `pid`, from each of its threads' `children` list. */
-function children(proc, pid) {
-    let tasks;
-    try {
-        tasks = readdirSync(join(proc, String(pid), "task"));
-    }
-    catch {
-        return [];
-    }
-    return tasks.flatMap((tid) => {
-        try {
-            return readFileSync(join(proc, String(pid), "task", tid, "children"), "utf8").split(" ").filter(Boolean).map(Number);
-        }
-        catch {
-            return [];
-        }
-    });
-}
-/** Whether the process `pid` was started with `name=value` in its environment (false when it cannot be read). */
-function marked(proc, pid, name, value) {
-    try {
-        return readFileSync(join(proc, String(pid), "environ"), "utf8").split("\0").includes(`${name}=${value}`);
-    }
-    catch {
-        return false;
-    }
-}
-/** Whether `mark` is still the process it was: same pid, same start ticks, not a zombie. Never pid 1 or below. */
-function same(proc, mark) {
-    return mark.pid > 1 && stat(proc, mark.pid)?.start === mark.start;
-}
-/** A process's command line for a message, best effort. */
-function commandLine(proc, pid) {
-    try {
-        return readFileSync(join(proc, String(pid), "cmdline"), "utf8").split("\0").filter(Boolean).join(" ") || "?";
-    }
-    catch {
-        return "?";
-    }
+const tableOf = (options) => options.table ?? (options.proc === undefined ? processTable() : procTable(options.proc));
+/** Whether `mark` is still the process it was: same pid, same start, not a zombie. Never pid 1 or below. */
+function same(look, mark) {
+    return mark.pid > 1 && look.info(mark.pid)?.start === mark.start;
 }
 const RECORD = /^(\d+)-(\d+)\.json$/;
 /**
@@ -89,7 +34,7 @@ export class CommandRecorder {
     /** The value of `COMMANDS_MARK` in this environment's commands. */
     token = randomUUID();
     #dir;
-    #proc;
+    #table;
     #instance;
     #everyMs;
     #boot;
@@ -102,10 +47,10 @@ export class CommandRecorder {
     #timer;
     constructor(dir, options = {}) {
         this.#dir = dir;
-        this.#proc = options.proc ?? "/proc";
+        this.#table = tableOf(options);
         this.#instance = options.instance ?? process.pid;
-        this.#everyMs = options.everyMs ?? 100;
-        this.#boot = bootId(this.#proc);
+        this.#everyMs = options.everyMs ?? this.#table.walkMs;
+        this.#boot = this.#table.bootId();
         this.#onError = options.onError;
     }
     /** A command is about to start. */
@@ -151,24 +96,25 @@ export class CommandRecorder {
         const boot = this.#boot;
         if (boot === undefined)
             return;
-        const own = stat(this.#proc, this.#instance);
+        const look = this.#table.snapshot();
+        const own = look.info(this.#instance);
         if (own === undefined)
             return;
         // New commands: children of this process that lead their own group (pi spawns each one so) and carry this
         // environment's mark. Once recorded, a leader stays its environment's whatever it execs next (same pid and start).
-        for (const pid of children(this.#proc, this.#instance)) {
-            const leader = stat(this.#proc, pid);
+        for (const pid of look.children(this.#instance)) {
+            const leader = look.info(pid);
             if (leader === undefined || leader.pgrp !== pid || leader.pgrp === own.pgrp)
                 continue;
             const key = `${pid}-${leader.start}`;
-            if (this.#records.has(key) || !marked(this.#proc, pid, COMMANDS_MARK, this.token))
+            if (this.#records.has(key) || !look.marked(pid, COMMANDS_MARK, this.token))
                 continue;
             this.#records.set(key, { leader: { pid, start: leader.start }, members: new Map() });
         }
         // Every record: walk from each of its processes still alive, the leader and every member, so a background worker whose
         // leader (or parent) exited and was reparented away is still followed, and so are the children it starts later.
         for (const [key, record] of this.#records) {
-            const live = [record.leader, ...record.members.values()].filter((mark) => same(this.#proc, mark));
+            const live = [record.leader, ...record.members.values()].filter((mark) => same(look, mark));
             if (live.length === 0) {
                 this.#records.delete(key);
                 this.#written.delete(key);
@@ -177,8 +123,8 @@ export class CommandRecorder {
             }
             let grew = !this.#written.has(key);
             const walk = (parent) => {
-                for (const child of children(this.#proc, parent)) {
-                    const s = stat(this.#proc, child);
+                for (const child of look.children(parent)) {
+                    const s = look.info(child);
                     if (s === undefined || child === record.leader.pid)
                         continue;
                     const known = record.members.get(child)?.start === s.start;
@@ -212,7 +158,7 @@ export class CommandRecorder {
  * again, and they are returned. Run only while holding the run (after its owner lock), before the Harness opens.
  */
 export async function reapCommands(dir, options = {}) {
-    const proc = options.proc ?? "/proc";
+    const table = tableOf(options);
     const signal = options.kill ?? ((target, name) => process.kill(target, name));
     let files;
     try {
@@ -221,8 +167,13 @@ export async function reapCommands(dir, options = {}) {
     catch {
         return { signalled: 0, survivors: [] };
     }
-    const boot = bootId(proc);
-    const own = stat(proc, process.pid);
+    if (files.length === 0) {
+        rmSync(dir, { recursive: true, force: true });
+        return { signalled: 0, survivors: [] };
+    }
+    const boot = table.bootId();
+    const before = table.snapshot();
+    const own = before.info(process.pid);
     let signalled = 0;
     /**
      * False for what is never a target: this process, its group, and a pid of 1 or below, since `kill(0)` is the caller's
@@ -255,19 +206,26 @@ export async function reapCommands(dir, options = {}) {
             rmSync(file, { force: true }); // another boot's pids mean nothing on this one
             continue;
         }
-        const leader = record.leader !== null && same(proc, record.leader) && kill(-record.leader.pid, record.leader) ? record.leader : null;
+        const leader = record.leader !== null && same(before, record.leader) && kill(-record.leader.pid, record.leader) ? record.leader : null;
         // A member that is the leader went with its group.
-        const members = (record.members ?? []).filter((member) => member.pid !== record.leader?.pid && same(proc, member) && kill(member.pid, member));
+        const members = (record.members ?? []).filter((member) => member.pid !== record.leader?.pid && same(before, member) && kill(member.pid, member));
         pending.push({ file, boot, leader, members });
     }
-    const alive = () => pending.flatMap((p) => [...(p.leader ? [p.leader] : []), ...p.members]).filter((mark) => same(proc, mark));
+    const alive = () => {
+        const marks = pending.flatMap((p) => [...(p.leader ? [p.leader] : []), ...p.members]);
+        if (marks.length === 0)
+            return marks;
+        const look = table.snapshot();
+        return marks.filter((mark) => same(look, mark));
+    };
     const deadline = Date.now() + (options.timeoutMs ?? 5_000);
     while (alive().length > 0 && Date.now() < deadline)
         await new Promise((resolve) => setTimeout(resolve, 10));
     const survivors = [];
+    const after = pending.length === 0 ? before : table.snapshot();
     for (const record of pending) {
-        const leader = record.leader !== null && same(proc, record.leader) ? record.leader : null;
-        const members = record.members.filter((member) => same(proc, member));
+        const leader = record.leader !== null && same(after, record.leader) ? record.leader : null;
+        const members = record.members.filter((member) => same(after, member));
         if (leader === null && members.length === 0) {
             rmSync(record.file, { force: true });
             continue;
@@ -288,10 +246,10 @@ export async function reapCommands(dir, options = {}) {
 export async function reapOrRefuse(dir, options = {}) {
     const reaped = await reapCommands(dir, options);
     if (reaped.survivors.length > 0) {
-        const proc = options.proc ?? "/proc";
+        const look = tableOf(options).snapshot();
         const pids = reaped.survivors.map((s) => s.pid);
         throw new HeldError("commands", `${pids.length} process(es) a killed incarnation's commands started are still alive after SIGKILL: ` +
-            `${reaped.survivors.map((s) => `pid ${s.pid} (${commandLine(proc, s.pid)})`).join(", ")}. ` +
+            `${reaped.survivors.map((s) => `pid ${s.pid} (${look.commandLine(s.pid)})`).join(", ")}. ` +
             `The run does not resume beside them. End them (kill -9 ${pids.join(" ")}, as their owner, or wait for them) and open the run again; ` +
             `they stay recorded in ${dir} until then.`);
     }

package/dist/confine.d.ts

@@ -37,8 +37,9 @@ export interface PinSpec {
     readonly strict?: boolean;
 }
 /**
- * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths to hand to pi's own implementation; every
- * path and message it returns is mapped back to the real one with `restore`. Close it when the operation is done.
+ * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths (by path, the real ones) to hand to pi's
+ * own implementation; every path and message it returns is mapped back to the real one with `restore`. Close it when
+ * the operation is done.
  */
 export declare class Pin {
     #private;
@@ -49,25 +50,50 @@ export declare class Pin {
     readonly dir: string;
     /** The target below `dir`, for operations that do not follow a last symlink. */
     readonly entry: string;
-    constructor(handle: FileHandle, canonical: string, name: string, dirMode: boolean);
-    /** `text` with the held paths replaced by the real ones. */
+    /**
+     * `held` is the walk's: whether it went by path, and then the held directory's real path; and the names of the
+     * confinement's roots (`Confinement`'s `names`).
+     */
+    constructor(handle: FileHandle, canonical: string, name: string, dirMode: boolean, held?: {
+        byPath: boolean;
+        path: string;
+        names?: readonly RootName[];
+    });
+    /** `text` with the held paths replaced by the real ones, and a root named as the caller names it. */
     translate(text: string): string;
     /** An error pi or Node raised on a held path, as a FileError that names the real one. */
     error(error: unknown, path: string): FileError;
     restore<T>(result: Result<T, FileError>): Result<T, FileError>;
-    /** Opens the target's last component, which is never followed, and returns its handle; the caller closes it. */
+    /**
+     * Opens the target's last component, which is never followed, and returns its handle; the caller closes it. By path,
+     * the directory's path must still name the directory held once the file is open.
+     */
     openFile(flags: number, mode?: number): Promise<FileHandle>;
     binaryReader(reader: BinaryReader): BinaryReader;
     /** The reader keeps the pin open: pi's reader names each entry through `dir` as it pages. */
     dirReader(reader: DirReader): DirReader;
     close(): Promise<void>;
 }
+/** A root's canonical path, as a pattern that matches it whole in a path or a message, and the name the caller gave it. */
+interface RootName {
+    readonly canonical: RegExp;
+    readonly named: string;
+}
 export declare class Confinement {
     #private;
     readonly work: string;
     readonly readOnly: readonly string[];
-    /** Canonical directories: `work` may be read and written, `readOnly` only read. */
-    constructor(work: string, readOnly: readonly string[]);
+    /** Whether the walk goes by path (macOS, which has no `/proc/self/fd`; see the top of this file). */
+    readonly byPath: boolean;
+    /**
+     * Canonical directories: `work` may be read and written, `readOnly` only read. `byPath` defaults to true on macOS only.
+     * `names` maps a canonical root to the path the caller names it by, where they differ (a root under a symlinked
+     * directory, as `/tmp` and `/var` are on macOS): results name paths under it as the caller does, as pi's own do.
+     */
+    constructor(work: string, readOnly: readonly string[], options?: {
+        readonly byPath?: boolean;
+        readonly names?: ReadonlyMap<string, string>;
+    });
     /**
      * Lets file operations write inside `dir` too: a directory this process just created (`createTempDir`) directly in a
      * read-only root, for the tool it is handed to. `dir` is that root joined with the new name, never resolved: if the
@@ -89,3 +115,6 @@ export declare class Confinement {
         create?: boolean;
     }): Promise<Pin>;
 }
+/** Whether `path` still names the directory `held` holds (same device and inode); false when it cannot be read. */
+export declare function namesHeld(path: string, held: FileHandle): Promise<boolean>;
+export {};