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

package/dist/env.js

@@ -0,0 +1,608 @@
+// The execution environment: pi's NodeExecutionEnv rooted at the run's work/ directory, with an environment id
+// that names the run, commands that cannot gain privilege (no_new_privs), optionally commands run as another user
+// (`runAs`, for an instance that runs as root in a container), file operations confined to work/ (confine.ts),
+// read-only built-in tools declared replay-safe, and the hook point for the workspace barrier. Tools run
+// on the host that holds the claim, against the claimed mount.
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { access, chmod, lchown, lstat, mkdir, mkdtemp, open, realpath, stat } from "node:fs/promises";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { withAbortSignal } from "@earendil-works/chord/context";
+import { defineExtension, hook, ToolTask } from "@earendil-works/pi-durable";
+import { err, ExecutionError, FileError, getOrThrow, ok } from "@earendil-works/pi-durable/env";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { CodingTools } from "@earendil-works/pi-durable/tools";
+import { COMMANDS_MARK, CommandRecorder } from "./commands.js";
+import { canonicalizeSync, confineHooks, Confinement, fileError, inside } from "./confine.js";
+import { PdaError } from "./errors.js";
+/**
+ * What `exec` returns once the factory's `cleanup()` ran: no command was started. Its `code` is pi's `spawn_error`
+ * (the command could not start), `reason` tells it apart from a program that failed to spawn.
+ */
+export class EnvClosedError extends ExecutionError {
+    reason = "env_closed";
+    constructor() {
+        super("spawn_error", "The environment is closed (its run released or was fenced): no command was started");
+        this.name = "EnvClosedError";
+    }
+}
+/** The environment cannot be built as asked. Exit 1. */
+export class EnvError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+const POLL_INTERVAL_MS = 1000;
+const SETPRIV = "/usr/bin/setpriv";
+const DEFAULT_PATH = "/usr/bin:/bin";
+/** Temporary directories are created under `<root>/tmp/`; the directory itself is 0755 whatever the umask. */
+const TEMP_DIR = "tmp";
+class ArchilExecutionEnv extends NodeExecutionEnv {
+    #scope;
+    #active = 0;
+    constructor(scope, options) {
+        super(options);
+        this.id = scope.id;
+        this.#scope = scope;
+    }
+    async exec(command, options, context) {
+        const { closing } = this.#scope;
+        // Checked before anything touches the file system, so a refusal is immediate even when the mount is hung.
+        if (closing.signal.aborted)
+            return err(new EnvClosedError());
+        this.#active++;
+        this.#scope.running.add(this);
+        this.#scope.recorder?.started();
+        try {
+            // A recorded environment marks its commands, so its recorder knows them from any other child of this process.
+            const recorder = this.#scope.recorder;
+            const run = recorder === undefined ? options : { ...options, env: { ...options?.env, [COMMANDS_MARK]: recorder.token } };
+            const confined = await this.#confine(command, run, context);
+            if (!confined.ok)
+                return confined;
+            // Again after the confinement lookups, which await; the signal then covers pi's own pre-spawn work: pi refuses
+            // before spawning once it is aborted, and kills a command that spawns after.
+            if (closing.signal.aborted)
+                return err(new EnvClosedError());
+            return await super.exec(confined.value, run, withAbortSignal(closing.signal, context));
+        }
+        finally {
+            this.#scope.recorder?.finished();
+            if (--this.#active === 0)
+                this.#scope.running.delete(this);
+        }
+    }
+    // `setpriv` replaces itself with the command (execvp), so the process, its group and its exit status are the
+    // command's own. A string command becomes the argv of the shell pi would have run it through, which is how
+    // setpriv gets in front of the shell; failures pi reports before spawning (no such program, no such shell) are
+    // reported the same way here instead of as setpriv's exit status.
+    async #confine(command, options, context) {
+        const { setpriv, noNewPrivs, runAs, shellPath, shellEnv } = this.#scope;
+        if (setpriv === undefined)
+            return ok(command);
+        const confine = [
+            setpriv,
+            // A root instance's capabilities stay with it: the command's bounding and inheritable sets are emptied too.
+            ...(runAs ? [`--reuid=${runAs.uid}`, `--regid=${runAs.gid}`, "--clear-groups", "--inh-caps=-all", "--bounding-set=-all"] : []),
+            ...(noNewPrivs ? ["--no-new-privs"] : []),
+            "--",
+        ];
+        const cwd = options?.cwd === undefined ? this.cwd : getOrDefault(await this.absolutePath(options.cwd, context), this.cwd);
+        const env = options?.inheritEnv === false ? { ...options.env } : { ...process.env, ...shellEnv, ...options?.env };
+        if (typeof command === "string") {
+            const shell = await resolveShell(shellPath, cwd, env);
+            return shell.ok ? ok([...confine, shell.value, "-c", command]) : shell;
+        }
+        const [program] = command;
+        if (program === undefined)
+            return ok(command);
+        if (!(await findProgram(program, cwd, env)))
+            return err(new ExecutionError("spawn_error", `spawn ${program} ENOENT`));
+        return ok([...confine, ...command]);
+    }
+    // File operations. Each one resolves its path to the file the kernel would reach and refuses it unless it lies in the
+    // workspace (reads may also use the read-only roots); the work is then done on handles held from the root down, so a
+    // component swapped for a symlink after the check is refused, not followed (confine.ts). Commands are not file
+    // operations: they run arbitrary code, and `exec`'s `cwd` is not confined. Methods not listed are lexical
+    // (`absolutePath`, `joinPath`), derived from these (`exists`, `readTextLines`), or not path-taking.
+    async #abs(path, context) {
+        return getOrThrow(await this.absolutePath(path, context));
+    }
+    async #pinned(path, context, pin, run) {
+        if (context.abortSignal?.aborted)
+            return err(new FileError("aborted", "aborted", path));
+        let held;
+        try {
+            held = await pin(this.#scope.confinement, await this.#abs(path, context));
+            return await run(held);
+        }
+        catch (error) {
+            return err(held === undefined ? fileError(error, path) : held.error(error, path));
+        }
+        finally {
+            await held?.close();
+        }
+    }
+    #entry(path, context, spec, run) {
+        return this.#pinned(path, context, (confinement, abs) => confinement.pinEntry(abs, path, spec), run);
+    }
+    /** Opens the file at `path` (a last symlink is resolved by the check, never by the open) and runs `run` on it. */
+    #file(path, context, spec, run) {
+        return this.#entry(path, context, { access: spec.access, follow: true, ...(spec.parents ? { parents: true } : {}) }, async (pin) => {
+            const handle = await pin.openFile(spec.flags);
+            try {
+                return await run(handle);
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+        });
+    }
+    async readTextFile(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.readTextFile(path, context);
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, async (handle) => ok(await handle.readFile({ encoding: "utf8", signal: context.abortSignal })));
+    }
+    async readBinaryFile(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.readBinaryFile(path, context);
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, async (handle) => ok(await handle.readFile({ signal: context.abortSignal })));
+    }
+    async openTextLineReader(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.openTextLineReader(path, context);
+        // pi opens the file again through the handle's own `/proc/self/fd` entry, which names that inode and no path.
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle) => super.openTextLineReader(`/proc/self/fd/${handle.fd}`, context));
+    }
+    async openBinaryReader(path, options, context) {
+        if (this.#scope.confinement === undefined)
+            return super.openBinaryReader(path, options, context);
+        return this.#entry(path, context, { access: "read", follow: options?.noFollow !== true }, async (pin) => {
+            // The target's last component was resolved by the check; pi must not follow it again.
+            const opened = await super.openBinaryReader(pin.entry, { noFollow: true }, context);
+            return opened.ok ? ok(pin.binaryReader(opened.value)) : pin.restore(opened);
+        });
+    }
+    async writeFile(path, content, context) {
+        if (this.#scope.confinement === undefined)
+            return super.writeFile(path, content, context);
+        const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC;
+        return this.#file(path, context, { access: "write", flags, parents: true }, async (handle) => {
+            await handle.writeFile(content, { signal: context.abortSignal });
+            return ok(undefined);
+        });
+    }
+    async appendFile(path, content, context) {
+        if (this.#scope.confinement === undefined)
+            return super.appendFile(path, content, context);
+        const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND;
+        return this.#file(path, context, { access: "write", flags, parents: true }, async (handle) => {
+            await handle.appendFile(content);
+            return ok(undefined);
+        });
+    }
+    async truncateFile(path, size, context) {
+        if (this.#scope.confinement === undefined)
+            return super.truncateFile(path, size, context);
+        if (!Number.isSafeInteger(size) || size < 0) {
+            return err(new FileError("invalid", "File size must be a non-negative safe integer", path));
+        }
+        return this.#file(path, context, { access: "write", flags: constants.O_RDWR }, async (handle) => {
+            await handle.truncate(size);
+            return ok(undefined);
+        });
+    }
+    async flushFile(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.flushFile(path, context);
+        return this.#file(path, context, { access: "write", flags: constants.O_RDWR }, async (handle) => {
+            await handle.sync();
+            return ok(undefined);
+        });
+    }
+    async renameFile(sourcePath, destinationPath, context) {
+        if (this.#scope.confinement === undefined)
+            return super.renameFile(sourcePath, destinationPath, context);
+        const spec = { access: "write", follow: false, strict: true };
+        return this.#entry(sourcePath, context, spec, (source) => this.#entry(destinationPath, context, spec, async (destination) => destination.restore(source.restore(await super.renameFile(source.entry, destination.entry, context)))));
+    }
+    async fileInfo(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.fileInfo(path, context);
+        return this.#entry(path, context, { access: "read", follow: false }, async (pin) => pin.restore(await super.fileInfo(pin.entry, context)));
+    }
+    async listDir(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.listDir(path, context);
+        return this.#pinned(path, context, (confinement, abs) => confinement.pinDir(abs, path, { access: "read" }), async (pin) => pin.restore(await super.listDir(pin.dir, context)));
+    }
+    async openDirReader(path, context) {
+        if (this.#scope.confinement === undefined)
+            return super.openDirReader(path, context);
+        // The reader names its entries through the held directory as it pages, so the pin lives until the reader closes.
+        if (context.abortSignal?.aborted)
+            return err(new FileError("aborted", "aborted", path));
+        let held;
+        try {
+            held = await this.#scope.confinement.pinDir(await this.#abs(path, context), path, { access: "read" });
+            const opened = await super.openDirReader(held.dir, context);
+            if (!opened.ok) {
+                const failure = err(held.error(opened.error, path));
+                await held.close();
+                return failure;
+            }
+            return ok(held.dirReader(opened.value));
+        }
+        catch (error) {
+            const failure = err(held === undefined ? fileError(error, path) : held.error(error, path));
+            await held?.close();
+            return failure;
+        }
+    }
+    async canonicalPath(path, context) {
+        const confinement = this.#scope.confinement;
+        if (confinement === undefined)
+            return super.canonicalPath(path, context);
+        try {
+            await confinement.locate(await this.#abs(path, context), path, "read", true);
+            const canonical = await super.canonicalPath(path, context);
+            if (canonical.ok && ![confinement.work, ...confinement.readOnly].some((root) => inside(canonical.value, root))) {
+                await confinement.locate(canonical.value, path, "read", true);
+            }
+            return canonical;
+        }
+        catch (error) {
+            return err(fileError(error, path));
+        }
+    }
+    async createDir(path, options, context) {
+        if (this.#scope.confinement === undefined)
+            return super.createDir(path, options, context);
+        if (options?.recursive === false) {
+            return this.#entry(path, context, { access: "write", follow: false }, async (pin) => pin.restore(await super.createDir(pin.entry, options, context)));
+        }
+        return this.#pinned(path, context, (confinement, abs) => confinement.pinDir(abs, path, { access: "write", create: true }), async () => ok(undefined));
+    }
+    async remove(path, options, context) {
+        if (this.#scope.confinement === undefined)
+            return super.remove(path, options, context);
+        let gone;
+        const removed = await this.#entry(path, context, { access: "write", follow: false, strict: true }, async (pin) => {
+            const result = pin.restore(await super.remove(pin.entry, options, context));
+            if (result.ok)
+                gone = pin.canonical;
+            return result;
+        });
+        if (gone !== undefined)
+            this.#scope.confinement.forgetWrites(gone); // a temp dir it was given, removed: its grant goes with it
+        // `force` ignores a missing target, a missing directory above it included.
+        return !removed.ok && removed.error.code === "not_found" && options?.force === true ? ok(undefined) : removed;
+    }
+    async watch(targets, onChange, context) {
+        const confinement = this.#scope.confinement;
+        if (confinement === undefined)
+            return super.watch(targets, onChange, context);
+        // A watch reports that something changed, never contents, and pi's watcher re-reads its paths on its own schedule
+        // (and reports a watched symlink's target under the symlink's name): the targets are checked once, here, and handed
+        // over as named, not held.
+        try {
+            for (const target of targets)
+                await confinement.locate(await this.#abs(target.path, context), target.path, "read", true);
+            return await super.watch(targets, onChange, context);
+        }
+        catch (error) {
+            return err(fileError(error, targets[0]?.path ?? "."));
+        }
+    }
+    // pi's `createTempFile` and the spill of a command's output both go through this method.
+    async createTempDir(prefix, context) {
+        if (context.abortSignal?.aborted)
+            return err(new FileError("aborted", "aborted"));
+        const { tempRoot, confinement, tempCanonical } = this.#scope;
+        try {
+            if ((await mkdir(tempRoot, { recursive: true, mode: 0o755 })) !== undefined)
+                await chmod(tempRoot, 0o755);
+            if (confinement === undefined || tempCanonical === undefined)
+                return ok(await mkdtemp(join(tempRoot, prefix ?? "tmp-")));
+            // The tool it is handed to may write in it (vision writes its source there); the rest of tmp/ stays read-only. It is
+            // made through a held handle of tmp/ that does not follow a link (a tmp/ a command replaced with one is refused here),
+            // and granted by name under the canonical tmp/, never resolved (a directory swapped for a link later grants nothing).
+            const held = await open(tempRoot, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            let name;
+            try {
+                name = basename(await mkdtemp(`/proc/self/fd/${held.fd}/${prefix ?? "tmp-"}`));
+            }
+            finally {
+                await held.close();
+            }
+            const dir = join(tempRoot, name);
+            await confineHooks.afterTempDir?.(dir);
+            confinement.allowWrites(join(tempCanonical, name));
+            return ok(dir);
+        }
+        catch (error) {
+            return err(fileError(error, tempRoot));
+        }
+    }
+}
+/**
+ * An environment whose commands run as `runAs`, which owns `work/` and everything pi's in-process file tools create under
+ * it. pi creates a file and its missing parent directories as this process's user (root, where `runAs` is used), so each
+ * creating call notes which entries under `work/` did not exist and hands those it created to `runAs` afterwards. Each
+ * entry is chowned through the confinement's pinned walk (`lchown` of `/proc/self/fd/<parent>/<name>`: no component is
+ * followed, and none can be swapped for a symlink in between); without confinement, only while the entry's parent still
+ * resolves inside `work/`. An entry that existed keeps its owner. A failed chown leaves the entry root's: a command that
+ * then cannot change it says so.
+ */
+class OwnedExecutionEnv extends ArchilExecutionEnv {
+    #closing;
+    #confinement;
+    #work;
+    #owner;
+    #workOwned;
+    constructor(scope, options, work, owner, workOwned) {
+        super(scope, options);
+        this.#closing = scope.closing.signal;
+        this.#confinement = scope.confinement;
+        this.#work = scope.confinement?.work ?? work;
+        this.#owner = owner;
+        this.#workOwned = workOwned;
+    }
+    async exec(command, options, context) {
+        // A closed factory refuses before touching the mount (ArchilExecutionEnv.exec); so does this.
+        if (!this.#closing.aborted)
+            await this.#workOwned();
+        return super.exec(command, options, context);
+    }
+    writeFile(path, content, context) {
+        return this.#creating(path, context, () => super.writeFile(path, content, context));
+    }
+    appendFile(path, content, context) {
+        return this.#creating(path, context, () => super.appendFile(path, content, context));
+    }
+    createDir(path, options, context) {
+        return this.#creating(path, context, () => super.createDir(path, options, context));
+    }
+    async #creating(path, context, call) {
+        await this.#workOwned();
+        const abs = getOrDefault(await this.absolutePath(path, context), resolve(this.cwd, path));
+        // The confinement's work/ is canonical, so the target is too (its last component is not followed).
+        const target = this.#confinement === undefined ? abs : join(canonicalizeSync(dirname(abs)), abs.slice(dirname(abs).length + 1));
+        const created = await missingWithin(this.#work, target);
+        const result = await call();
+        if (result.ok)
+            for (const entry of created)
+                if (!(await this.#give(entry)))
+                    break;
+        return result;
+    }
+    async #give(path) {
+        const { uid, gid } = this.#owner;
+        if (this.#confinement === undefined) {
+            const parent = await realpath(dirname(path)).catch(() => undefined);
+            const work = await realpath(this.#work).catch(() => undefined);
+            if (parent === undefined || work === undefined || !inside(parent, work))
+                return false;
+            return lchown(path, uid, gid).then(() => true, () => false);
+        }
+        let pin;
+        try {
+            pin = await this.#confinement.pinEntry(path, path, { access: "write", follow: false });
+            await lchown(pin.entry, uid, gid);
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            await pin?.close();
+        }
+    }
+}
+/** `target` and its ancestors below `work` that do not exist, outermost first; empty outside `work` or on any doubt. */
+async function missingWithin(work, target) {
+    const missing = [];
+    for (let path = target; path !== work && inside(path, work); path = dirname(path)) {
+        try {
+            await lstat(path);
+            return missing;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return [];
+            missing.unshift(path);
+        }
+    }
+    return inside(target, work) ? missing : [];
+}
+/** `work/` owned by `owner`, checked once per factory; a failure (no `work/` yet, a fenced mount) is retried next time. */
+function ownedOnce(work, owner) {
+    let done;
+    return () => (done ??= (async () => {
+        const st = await lstat(work);
+        if (st.uid !== owner.uid || st.gid !== owner.gid)
+            await lchown(work, owner.uid, owner.gid);
+    })().catch(() => {
+        done = undefined;
+    }));
+}
+function getOrDefault(result, fallback) {
+    return result.ok ? result.value : fallback;
+}
+/** The shell pi runs a string command through: `shellPath`, else /bin/bash, else bash on PATH, else sh. */
+async function resolveShell(shellPath, cwd, env) {
+    if (shellPath !== undefined && shellPath !== "") {
+        return (await exists(shellPath))
+            ? ok(shellPath)
+            : err(new ExecutionError("shell_unavailable", `Custom shell path not found: ${shellPath}`));
+    }
+    if (await exists("/bin/bash"))
+        return ok("/bin/bash");
+    return ok((await findProgram("bash", cwd, env)) ? "bash" : "sh");
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether execvp would find an executable regular file for `program`: with a slash relative to `cwd`, else on PATH. */
+async function findProgram(program, cwd, env) {
+    const candidates = program.includes("/")
+        ? [resolve(cwd, program)]
+        : (env.PATH ?? DEFAULT_PATH).split(delimiter).map((dir) => resolve(cwd, dir === "" ? "." : dir, program));
+    for (const candidate of candidates) {
+        try {
+            if (!(await stat(candidate)).isFile())
+                continue;
+            await access(candidate, constants.X_OK);
+            return true;
+        }
+        catch {
+            // Not here; execvp tries the next directory.
+        }
+    }
+    return false;
+}
+function requireSetpriv(path) {
+    try {
+        if (!statSync(path).isFile())
+            throw new Error("not a file");
+        accessSync(path, constants.X_OK);
+        return path;
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new EnvError("SETPRIV_UNAVAILABLE", `commands run under no_new_privs (and as runAs) through setpriv (util-linux), which is not usable at ${path}: ${reason}. ` +
+            "Install util-linux, point setprivPath at it, or pass noNewPrivs: false on a host that already confines commands.", { cause });
+    }
+}
+/**
+ * The roots, canonical once here: file operations may use the workspace, the claim's `tmp/` (read only, but for the
+ * directories `createTempDir` hands out, which are writable) and `readRoots`.
+ * Taken at construction, before any agent runs, so a symlink an agent puts in place of `work` or `tmp` later cannot widen
+ * them: it resolves outside the roots and is refused.
+ */
+function requireConfinement(claim, readRoots) {
+    if (!existsSync("/proc/self/fd")) {
+        throw new EnvError("PROC_UNAVAILABLE", "file operations are confined by walking paths through /proc/self/fd, which is not available here. " +
+            "Mount /proc, or pass confineFiles: false where the file paths are confined some other way.");
+    }
+    const tmp = join(canonicalizeSync(claim.root), TEMP_DIR);
+    return new Confinement(canonicalizeSync(claim.work), [tmp, ...readRoots.map((root) => canonicalizeSync(root))]);
+}
+export function archilEnv(claim, options = {}) {
+    const id = ["archil", claim.disk, claim.root].filter((part) => part !== undefined && part !== "").join(":");
+    const running = new Set();
+    const runAs = options.runAs;
+    if (runAs && ![runAs.uid, runAs.gid].every((n) => Number.isSafeInteger(n) && n >= 0)) {
+        throw new EnvError("INVALID_RUN_AS", `runAs needs a numeric uid and gid, got ${JSON.stringify(runAs)}`);
+    }
+    const noNewPrivs = options.noNewPrivs !== false;
+    const setpriv = noNewPrivs || runAs ? requireSetpriv(options.setprivPath ?? SETPRIV) : undefined;
+    const confinement = options.confineFiles === false ? undefined : requireConfinement(claim, options.readRoots ?? []);
+    const scope = {
+        id,
+        tempRoot: join(claim.root, TEMP_DIR),
+        setpriv,
+        noNewPrivs,
+        runAs,
+        shellPath: options.shellPath,
+        shellEnv: options.shellEnv,
+        running,
+        closing: new AbortController(),
+        confinement,
+        tempCanonical: confinement === undefined ? undefined : join(canonicalizeSync(claim.root), TEMP_DIR),
+        // A record that cannot be written (a full disk) leaves a command the next open could miss: said once on stderr, and
+        // the recorder keeps trying; the run goes on.
+        recorder: claim.commands === undefined
+            ? undefined
+            : new CommandRecorder(claim.commands, {
+                onError: (error) => process.stderr.write(`pi-durable-disk: cannot record the run's commands in ${claim.commands}: ${String(error)}\n`),
+            }),
+    };
+    const workOwned = runAs ? ownedOnce(claim.work, runAs) : undefined;
+    const build = (target) => {
+        const envOptions = {
+            cwd: target.cwd === undefined ? claim.work : resolve(claim.work, target.cwd),
+            watch: { mode: "polling", pollIntervalMs: POLL_INTERVAL_MS, ...options.watch },
+            ...(options.shellPath === undefined ? {} : { shellPath: options.shellPath }),
+            ...(options.shellEnv === undefined ? {} : { shellEnv: options.shellEnv }),
+        };
+        return runAs && workOwned ? new OwnedExecutionEnv(scope, envOptions, claim.work, runAs, workOwned) : new ArchilExecutionEnv(scope, envOptions);
+    };
+    const cleanup = async (context) => {
+        scope.closing.abort();
+        await Promise.all([...running].map((env) => env.cleanup(context)));
+        scope.recorder?.close();
+    };
+    return Object.assign(build, { id, cleanup });
+}
+/** Built-in tools that only read. A tool in this set is declared `replay: "safe"`. */
+export const READ_ONLY_TOOLS = new Set(["read", "ls", "find", "grep"]);
+/** Built-in tools that can change the workspace; their results follow the workspace barrier. */
+export const WRITING_TOOLS = new Set(["write", "edit", "bash", "powershell"]);
+/** The tool declared `replay: "safe"`: an interrupted call reruns on recovery instead of reporting `interrupted`. */
+export function replaySafe(tool) {
+    return { ...tool, replay: "safe" };
+}
+/** `tools` with every read-only one declared replay-safe; the others, and the input array, are untouched. */
+export function markReadOnlySafe(tools, readOnly = READ_ONLY_TOOLS) {
+    return tools.map((tool) => (readOnly.has(tool.name) ? replaySafe(tool) : tool));
+}
+/**
+ * pi's `CodingTools` with `read` declared replay-safe. It keeps pi's extension name, so installing it replaces
+ * `CodingTools` in place. `write`, `edit` and `bash` stay as pi ships them (unsafe). pi 1.1.0 ships no ls, find or
+ * grep; an app that adds them declares them safe with `markReadOnlySafe`.
+ */
+export const ArchilCodingTools = defineExtension({
+    name: CodingTools.name,
+    tools: markReadOnlySafe(CodingTools.tools ?? []),
+});
+/**
+ * The hook point for the rule that the workspace changes a tool made are durable before its result is committed.
+ * Install this extension only when the result commit's own fsync does not already satisfy the rule; with it
+ * not installed nothing runs. `barrier` is the claim's (`claim.barrier()`), called after a writing tool ran and before
+ * pi appends its result entry, for the calls whose tool name is in `options.tools`.
+ *
+ * pi reports and ignores an `afterTool` hook that throws, so a failed barrier cannot hold the result back by throwing.
+ * It replaces the result with an error result carrying the diagnostic `workspace_not_durable`: a success never commits
+ * for a workspace that is not durable. The host decides separately whether a failed barrier means the claim is fenced.
+ */
+export function workspaceBarrier(barrier, options = {}) {
+    const writing = new Set(options.tools ?? WRITING_TOOLS);
+    return defineExtension({
+        name: "archil-workspace-barrier",
+        hooks: [
+            hook(ToolTask, {
+                afterTool: async (call, result, _api, context) => {
+                    if (!writing.has(call.name))
+                        return undefined;
+                    try {
+                        await barrier(call, context);
+                        return undefined;
+                    }
+                    catch (error) {
+                        // An aborted invocation must propagate: pi rethrows hook errors only while it is aborted.
+                        if (context.abortSignal?.aborted)
+                            throw error;
+                        return notDurable(result, error);
+                    }
+                },
+            }),
+        ],
+    });
+}
+function notDurable(result, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+        ...result,
+        isError: true,
+        diagnostics: [
+            ...(result.diagnostics ?? []),
+            { severity: "error", code: "workspace_not_durable", message: `The workspace could not be made durable: ${reason}` },
+        ],
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/** EX_TEMPFAIL: the claim was revoked or its mount failed; nothing this process writes can become durable. */
+export declare const EXIT_FENCED = 75;
+/**
+ * Someone else holds the run: another client's delegation, another process's owner lock, another store connection. A
+ * held delegation is live or orphaned (its client gone); the supervisor revokes orphans.
+ */
+export declare const EXIT_HELD = 76;
+export declare class PdaError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        exitCode?: number;
+    });
+}
+/** The claim is lost or its mount failed. Never retried on the same handle; the process exits 75. */
+export declare class FencedError extends PdaError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        code?: string;
+    });
+}
+/** `commands`: processes a killed incarnation's commands left that did not die when the next open killed them. */
+export type Holder = "claim" | "owner-lock" | "store" | "commands";
+/** Someone else holds the run (see `Holder`). The process exits 76. */
+export declare class HeldError extends PdaError {
+    readonly holder: Holder;
+    constructor(holder: Holder, message: string, options?: {
+        cause?: unknown;
+        code?: string;
+    });
+}
+export type ClaimErrorCode = "INVALID_ARGUMENT" | "MOUNTPOINT_BUSY" | "MOUNTPOINT_NOT_EMPTY" | "MOUNT_FAILED" | "CLAIM_NOT_VERIFIED" | "ARCHIL_CLI_FAILED" | "UNMOUNT_FAILED" | "DEAD_MOUNT_CLEANUP_FAILED" | "CLAIM_RELEASED" | "CONTROL_API_FAILED";
+/** Any other claim failure (bad input, a refused or unverifiable mount, a CLI or control API failure). Exit 1. */
+export declare class ClaimError extends PdaError {
+    constructor(code: ClaimErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function exitCodeFor(err: unknown): number;
+/**
+ * Any error writing a file the claim owns (its probe, `run.json`, `owner.lock`, the run directory itself) is a fence. A
+ * revoked mount answers such writes with EIO, EROFS, ENOENT, SQLITE_CANTOPEN or a success into its local cache,
+ * so no errno is evidence that the claim is still held. Taking the owner lock is not a write: a lock
+ * another process holds is `HeldError("owner-lock")`.
+ */
+export declare function ownWriteFenced(what: string, cause: unknown): FencedError;