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

package/dist/commands.d.ts

@@ -0,0 +1,67 @@
+/** 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. */
+export interface ProcessMark {
+    readonly pid: number;
+    readonly start: number;
+}
+/** What a record holds: a command's group leader (null once only members of it outlived a reap) and the descendants seen. */
+export interface CommandRecord {
+    readonly boot: string;
+    readonly leader: ProcessMark | null;
+    readonly members: readonly ProcessMark[];
+}
+/** What a reap did: how many processes it signalled, and those still alive at its deadline (kept for the next open). */
+export interface Reaped {
+    readonly signalled: number;
+    readonly survivors: readonly ProcessMark[];
+}
+export interface CommandsOptions {
+    /** The `/proc` to read; for tests. */
+    readonly proc?: string;
+    /** How a reap signals; default `process.kill`. For tests. */
+    readonly kill?: (target: number, signal: NodeJS.Signals) => void;
+}
+/**
+ * Records this environment's command groups under this process while commands run. `started()` and `finished()` bracket
+ * each command, which carries `COMMANDS_MARK=<token>` in its environment; while any runs, the tree is walked soon after a
+ * start and then every `everyMs`. A record is written when its group gains a process and removed once nothing in it is
+ * alive. A walk that fails (a record cannot be written: a full disk) goes to `onError` the first time, never out of a
+ * timer, and the next walk tries again.
+ */
+export declare class CommandRecorder {
+    #private;
+    /** The value of `COMMANDS_MARK` in this environment's commands. */
+    readonly token: `${string}-${string}-${string}-${string}-${string}`;
+    constructor(dir: string, options?: CommandsOptions & {
+        readonly instance?: number;
+        readonly everyMs?: number;
+        readonly onError?: (error: unknown) => void;
+    });
+    /** A command is about to start. */
+    started(): void;
+    /** A command ended (its result is in). The last one stops the walks after a final one. */
+    finished(): void;
+    /** Stops recording (the environment closed); the records stay for the next open. */
+    close(): void;
+    /** One walk. It is called from timers, so it never throws: a failure goes to `onError` once, and the next walk retries. */
+    scan(): void;
+}
+/**
+ * Ends what a previous incarnation's commands left running: for each record of this boot, the leader's whole group when
+ * the leader is still the recorded process, and each recorded descendant that still is. Waits up to `timeoutMs` until
+ * none of them is alive. A record whose processes are all gone is removed; one that still names a live process (it did
+ * not die at the deadline: a process in an uninterruptible wait) is rewritten with just those, so the next open tries
+ * again, and they are returned. Run only while holding the run (after its owner lock), before the Harness opens.
+ */
+export declare function reapCommands(dir: string, options?: CommandsOptions & {
+    readonly timeoutMs?: number;
+}): Promise<Reaped>;
+/**
+ * `reapCommands` at an open: refuses the run (`HeldError("commands")`, exit 76) when a process a killed incarnation's
+ * commands left is still alive after it, since the run must not resume beside it. Its record stays, and the next open
+ * tries again.
+ */
+export declare function reapOrRefuse(dir: string, options?: CommandsOptions & {
+    readonly timeoutMs?: number;
+}): Promise<Reaped>;

package/dist/commands.js

@@ -0,0 +1,299 @@
+// 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.
+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";
+/** 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 RECORD = /^(\d+)-(\d+)\.json$/;
+/**
+ * Records this environment's command groups under this process while commands run. `started()` and `finished()` bracket
+ * each command, which carries `COMMANDS_MARK=<token>` in its environment; while any runs, the tree is walked soon after a
+ * start and then every `everyMs`. A record is written when its group gains a process and removed once nothing in it is
+ * alive. A walk that fails (a record cannot be written: a full disk) goes to `onError` the first time, never out of a
+ * timer, and the next walk tries again.
+ */
+export class CommandRecorder {
+    /** The value of `COMMANDS_MARK` in this environment's commands. */
+    token = randomUUID();
+    #dir;
+    #proc;
+    #instance;
+    #everyMs;
+    #boot;
+    #onError;
+    #reported = false;
+    #records = new Map();
+    /** The records on disk, by key; a group's first walk writes its record even before it has members. */
+    #written = new Set();
+    #active = 0;
+    #timer;
+    constructor(dir, options = {}) {
+        this.#dir = dir;
+        this.#proc = options.proc ?? "/proc";
+        this.#instance = options.instance ?? process.pid;
+        this.#everyMs = options.everyMs ?? 100;
+        this.#boot = bootId(this.#proc);
+        this.#onError = options.onError;
+    }
+    /** A command is about to start. */
+    started() {
+        if (this.#boot === undefined)
+            return; // nothing could verify a record on the next open
+        if (this.#active++ === 0) {
+            this.#timer = setInterval(() => this.scan(), this.#everyMs);
+            this.#timer.unref();
+        }
+        setTimeout(() => this.scan(), 20).unref();
+    }
+    /** A command ended (its result is in). The last one stops the walks after a final one. */
+    finished() {
+        if (this.#boot === undefined || this.#active === 0)
+            return;
+        if (--this.#active === 0) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+            this.scan();
+        }
+    }
+    /** Stops recording (the environment closed); the records stay for the next open. */
+    close() {
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+        this.#active = 0;
+    }
+    /** One walk. It is called from timers, so it never throws: a failure goes to `onError` once, and the next walk retries. */
+    scan() {
+        try {
+            this.#scan();
+        }
+        catch (error) {
+            if (this.#reported)
+                return;
+            this.#reported = true;
+            this.#onError?.(error);
+        }
+    }
+    /** Record what is new under each of this environment's command groups, and drop the records of groups that are gone. */
+    #scan() {
+        const boot = this.#boot;
+        if (boot === undefined)
+            return;
+        const own = stat(this.#proc, 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);
+            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))
+                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));
+            if (live.length === 0) {
+                this.#records.delete(key);
+                this.#written.delete(key);
+                rmSync(join(this.#dir, `${key}.json`), { force: true });
+                continue;
+            }
+            let grew = !this.#written.has(key);
+            const walk = (parent) => {
+                for (const child of children(this.#proc, parent)) {
+                    const s = stat(this.#proc, child);
+                    if (s === undefined || child === record.leader.pid)
+                        continue;
+                    const known = record.members.get(child)?.start === s.start;
+                    if (!known) {
+                        record.members.set(child, { pid: child, start: s.start });
+                        grew = true;
+                    }
+                    if (!known || !live.some((mark) => mark.pid === child))
+                        walk(child);
+                }
+            };
+            for (const mark of live)
+                walk(mark.pid);
+            if (grew)
+                this.#write(key, { boot, leader: record.leader, members: [...record.members.values()] });
+        }
+    }
+    #write(key, record) {
+        mkdirSync(this.#dir, { recursive: true, mode: 0o700 });
+        const file = join(this.#dir, `${key}.json`);
+        writeFileSync(`${file}.tmp`, JSON.stringify(record));
+        renameSync(`${file}.tmp`, file);
+        this.#written.add(key);
+    }
+}
+/**
+ * Ends what a previous incarnation's commands left running: for each record of this boot, the leader's whole group when
+ * the leader is still the recorded process, and each recorded descendant that still is. Waits up to `timeoutMs` until
+ * none of them is alive. A record whose processes are all gone is removed; one that still names a live process (it did
+ * not die at the deadline: a process in an uninterruptible wait) is rewritten with just those, so the next open tries
+ * 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 signal = options.kill ?? ((target, name) => process.kill(target, name));
+    let files;
+    try {
+        files = readdirSync(dir).filter((name) => RECORD.test(name));
+    }
+    catch {
+        return { signalled: 0, survivors: [] };
+    }
+    const boot = bootId(proc);
+    const own = stat(proc, 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
+     * group and `kill(-1)` every process the user may signal.
+     */
+    const kill = (target, mark) => {
+        if (!(mark.pid > 1) || mark.pid === process.pid || (target < 0 && -target === own?.pgrp))
+            return false;
+        try {
+            signal(target, "SIGKILL");
+            signalled++;
+        }
+        catch {
+            // gone between the check and the kill, or not ours to signal: still a target, a survivor if it is alive
+        }
+        return true;
+    };
+    const pending = [];
+    for (const name of files) {
+        const file = join(dir, name);
+        let record;
+        try {
+            record = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            rmSync(file, { force: true }); // a torn write of a record names nothing
+            continue;
+        }
+        if (boot === undefined || record.boot !== boot) {
+            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;
+        // 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));
+        pending.push({ file, boot, leader, members });
+    }
+    const alive = () => pending.flatMap((p) => [...(p.leader ? [p.leader] : []), ...p.members]).filter((mark) => same(proc, 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 = [];
+    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));
+        if (leader === null && members.length === 0) {
+            rmSync(record.file, { force: true });
+            continue;
+        }
+        survivors.push(...(leader ? [leader] : []), ...members);
+        writeFileSync(`${record.file}.tmp`, JSON.stringify({ boot: record.boot, leader, members }));
+        renameSync(`${record.file}.tmp`, record.file);
+    }
+    if (survivors.length === 0)
+        rmSync(dir, { recursive: true, force: true });
+    return { signalled, survivors };
+}
+/**
+ * `reapCommands` at an open: refuses the run (`HeldError("commands")`, exit 76) when a process a killed incarnation's
+ * commands left is still alive after it, since the run must not resume beside it. Its record stays, and the next open
+ * tries again.
+ */
+export async function reapOrRefuse(dir, options = {}) {
+    const reaped = await reapCommands(dir, options);
+    if (reaped.survivors.length > 0) {
+        const proc = options.proc ?? "/proc";
+        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(", ")}. ` +
+            `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.`);
+    }
+    return reaped;
+}

package/dist/confine.d.ts

@@ -14,6 +14,8 @@ export declare class PathOutsideWorkError extends FileError {
 /** Test seam: runs after a path was resolved and checked, before anything is opened. */
 export declare const confineHooks: {
     afterCheck?: (canonical: string) => Promise<void> | void;
+    /** After `createTempDir` made a directory and before it is granted (a command may act in between). */
+    afterTempDir?: (dir: string) => Promise<void> | void;
 };
 /** pi's mapping from a Node error to its `FileError` codes (pi does not export it). */
 export declare function fileError(error: unknown, path: string): FileError;
@@ -61,10 +63,19 @@ export declare class Pin {
     close(): Promise<void>;
 }
 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[]);
+    /**
+     * 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
+     * directory is later swapped for a link, a path through it resolves elsewhere and is refused.
+     */
+    allowWrites(dir: string): void;
+    /** `dir` was removed: writes inside it, or inside any handed directory below it, are no longer allowed. */
+    forgetWrites(dir: string): void;
     /** Resolves `abs` and refuses it unless it lies under an allowed root; returns the root that holds it. */
     locate(abs: string, original: string, access: "read" | "write", follow: boolean): Promise<{
         canonical: string;

package/dist/confine.js

@@ -213,15 +213,32 @@ const changed = (path) => new PathOutsideWorkError(path, "changed", `${path}: a
 export class Confinement {
     work;
     readOnly;
+    /** Directories handed out for writing after construction (the environment's temp dirs), canonical. */
+    #handed = new Set();
     /** Canonical directories: `work` may be read and written, `readOnly` only read. */
     constructor(work, readOnly) {
         this.work = work;
         this.readOnly = readOnly;
     }
+    /**
+     * 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
+     * directory is later swapped for a link, a path through it resolves elsewhere and is refused.
+     */
+    allowWrites(dir) {
+        if (this.readOnly.some((root) => dirname(dir) === root))
+            this.#handed.add(dir);
+    }
+    /** `dir` was removed: writes inside it, or inside any handed directory below it, are no longer allowed. */
+    forgetWrites(dir) {
+        for (const handed of this.#handed)
+            if (inside(handed, dir))
+                this.#handed.delete(handed);
+    }
     /** Resolves `abs` and refuses it unless it lies under an allowed root; returns the root that holds it. */
     async locate(abs, original, access, follow) {
         const canonical = follow ? await canonicalize(abs) : join(await canonicalize(dirname(abs)), basename(abs));
-        const roots = access === "write" ? [this.work] : [this.work, ...this.readOnly];
+        const roots = access === "write" ? [this.work, ...this.#handed] : [this.work, ...this.#handed, ...this.readOnly];
         const root = roots.find((candidate) => inside(canonical, candidate));
         if (root === undefined) {
             const where = canonical === abs ? "" : ` (it resolves to ${canonical})`;
@@ -235,7 +252,12 @@ export class Confinement {
         await confineHooks.afterCheck?.(canonical);
         const names = relative(root, canonical);
         if (names.length === 0 && spec.strict === true) {
-            throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
+            // a handed directory itself (a tool removing the temp dir it was given): pinned as an entry of the read-only root that
+            // holds it, so it can go; the workspace root never can
+            const holder = this.#handed.has(root) ? this.readOnly.find((candidate) => dirname(root) === candidate) : undefined;
+            if (holder === undefined)
+                throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
+            return new Pin(await walk(holder, [], "none", canonical), canonical, basename(root), false);
         }
         const name = names.pop() ?? "";
         const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical);

package/dist/env.d.ts

@@ -12,6 +12,11 @@ export interface ArchilEnvClaim {
     readonly work: string;
     /** The disk's id; part of the environment id when present. */
     readonly disk?: string;
+    /**
+     * Where the commands this environment starts are recorded, so that the next open of the claim ends what a killed
+     * incarnation left running (`reapCommands`). Set by a claim that nothing else cleans up after: a local run's.
+     */
+    readonly commands?: string;
 }
 export interface ArchilEnvOptions {
     /** How `watch` runs. Polling is the default because a FUSE mount does not report changes made elsewhere. */
@@ -34,8 +39,8 @@ export interface ArchilEnvOptions {
     readonly confineFiles?: boolean;
     /**
      * Directories file operations may read but never write, besides the workspace and the claim's `tmp/` (where a bash
-     * command's spilled output lives and which the bash tool names to the model). For an app's own skills or reference
-     * material.
+     * command's spilled output lives and which the bash tool names to the model; a directory `createTempDir` returned is
+     * writable too, for the tool it was handed to). For an app's own skills or reference material.
      */
     readonly readRoots?: readonly string[];
     /**
@@ -72,7 +77,8 @@ export declare class EnvError extends PdaError {
  * resumed run on another host has the same identity. Temporary files and directories (a bash command's spilled
  * `pi-output-*.log` among them) live under `<root>/tmp/`, inside the claim and outside `work/`, so a path a result
  * names still exists after a takeover on another host. Commands run under no_new_privs unless `noNewPrivs` is false, and
- * every file operation is confined to the workspace (reads also to `tmp/` and `readRoots`) unless `confineFiles` is false.
+ * every file operation is confined to the workspace (reads also to `tmp/` and `readRoots`, writes also inside a directory
+ * `createTempDir` returned) unless `confineFiles` is false.
  */
 export interface ArchilEnvFactory {
     /** Rooted at the claim's `work/`; an agent `cwd` is resolved against it. */
@@ -101,7 +107,7 @@ export declare function replaySafe<T extends ToolRegistration>(tool: T): T;
 export declare function markReadOnlySafe<T extends ToolRegistration>(tools: readonly T[], readOnly?: ReadonlySet<string>): T[];
 /**
  * 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.0.4 ships no ls, find or
+ * `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 declare const ArchilCodingTools: Extension;

package/dist/env.js

@@ -4,14 +4,15 @@
 // 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, realpath, stat } from "node:fs/promises";
-import { delimiter, dirname, join, resolve } from "node:path";
+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 { canonicalizeSync, Confinement, fileError, inside } from "./confine.js";
+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`
@@ -50,17 +51,22 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
             return err(new EnvClosedError());
         this.#active++;
         this.#scope.running.add(this);
+        this.#scope.recorder?.started();
         try {
-            const confined = await this.#confine(command, options, context);
+            // 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, options, withAbortSignal(closing.signal, context));
+            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);
         }
@@ -259,7 +265,15 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
     async remove(path, options, context) {
         if (this.#scope.confinement === undefined)
             return super.remove(path, options, context);
-        const removed = await this.#entry(path, context, { access: "write", follow: false, strict: true }, async (pin) => pin.restore(await super.remove(pin.entry, 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;
     }
@@ -283,11 +297,27 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
     async createTempDir(prefix, context) {
         if (context.abortSignal?.aborted)
             return err(new FileError("aborted", "aborted"));
-        const { tempRoot } = this.#scope;
+        const { tempRoot, confinement, tempCanonical } = this.#scope;
         try {
             if ((await mkdir(tempRoot, { recursive: true, mode: 0o755 })) !== undefined)
                 await chmod(tempRoot, 0o755);
-            return ok(await mkdtemp(join(tempRoot, prefix ?? "tmp-")));
+            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));
@@ -450,7 +480,8 @@ function requireSetpriv(path) {
     }
 }
 /**
- * The roots, canonical once here: file operations may use the workspace, the claim's `tmp/` (read only) and `readRoots`.
+ * 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.
  */
@@ -483,6 +514,14 @@ export function archilEnv(claim, options = {}) {
         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) => {
@@ -497,6 +536,7 @@ export function archilEnv(claim, options = {}) {
     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 });
 }
@@ -514,7 +554,7 @@ export function markReadOnlySafe(tools, readOnly = READ_ONLY_TOOLS) {
 }
 /**
  * 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.0.4 ships no ls, find or
+ * `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({

package/dist/errors.d.ts

@@ -20,7 +20,8 @@ export declare class FencedError extends PdaError {
         code?: string;
     });
 }
-export type Holder = "claim" | "owner-lock" | "store";
+/** `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;

package/dist/errors.js

@@ -25,7 +25,7 @@ export class FencedError extends PdaError {
         super(options.code ?? "FENCED", message, { cause: options.cause, exitCode: EXIT_FENCED });
     }
 }
-const HELD_CODES = { claim: "CLAIM_HELD", "owner-lock": "OWNER_LOCK_HELD", store: "STORE_BUSY" };
+const HELD_CODES = { claim: "CLAIM_HELD", "owner-lock": "OWNER_LOCK_HELD", store: "STORE_BUSY", commands: "COMMANDS_ALIVE" };
 /** Someone else holds the run (see `Holder`). The process exits 76. */
 export class HeldError extends PdaError {
     holder;

package/dist/hosts/daytona-launch.js

@@ -40,7 +40,9 @@ function writeState(path, state) {
     writeFileSync(`${path}.tmp`, `${JSON.stringify(state)}\n`, { mode: 0o600 });
     renameSync(`${path}.tmp`, path);
 }
-const alive = (pid, ticks) => pid !== null && ticks !== null && procStartTicks(pid) === ticks;
+// Only a real process with its start ticks: `stop` signals these pids, the instance's as a group, and a pid of 1 or below
+// names a group (`kill(-1)` is every process this user may signal). The state file holds whatever was written there.
+const alive = (pid, ticks) => Number.isInteger(pid) && pid > 1 && typeof ticks === "number" && procStartTicks(pid) === ticks;
 /** running while either process lives; otherwise stopped after a clean exit, failed after any other end. */
 export function launchStatus(dir, name) {
     const state = readState(dir, name);