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

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.0-beta.13 (2026-10-14)
+
+**pi-durable 1.1**
+- The peer ranges of `@earendil-works/pi-durable` and `@earendil-works/chord` widen from `~1.0.4` to `>=1.0.4 <1.2.0`:
+  the package installs beside pi-durable 1.1 and still beside 1.0.4. It is developed against 1.1.0, and a CI job
+  (`pi-durable-disk-pi-floor`) runs its whole suite again on pi-durable, chord and pi-ai 1.0.4, the lowest the range
+  accepts. The conformance minimum follows the installed version (23 cases on 1.0.4, 24 on 1.1), and the scan-order
+  control is skipped, with its reason, where the installed `Storage` contract has no order.
+- pi-durable 1.1.0 requires a `Storage` to honour `order` on its conversation, entry, task and submission scans and to
+  continue a cursor in the order it was returned with. The store's scans are pi's `SqliteStorage` behind the fenced
+  database, so they do: pi-durable 1.1.0's storage conformance suite (24 cases, one of them the scans in either order)
+  passes on both profiles, and a control shows the runner fails a storage that drops `order`.
+- What the package reads of pi's internals is unchanged in 1.1.0: `durable_metadata.next_seq` for the seal, and the
+  `retry` and `poll` checkpoints of generation and compaction for parking. Each is read off what the installed pi wrote:
+  the seal test commits through pi's storage, a park test waits on a real retry, and a new test waits on a real
+  deferred answer (pi's poll phase), so a version that moved either shape fails a test rather than this sentence.
+- The Docker runtime image installs pi-durable, pi-ai and chord 1.1.0.
+
+**A dead client's private directories**
+- Each client holds delegations on its own private directories too, `.archil/client-<clientId>` and its `unlinked/`, which the
+  control API lists with no path. A client that dies (its FUSE daemon killed under a running instance, a lost host) leaves them
+  orphaned after the run's own delegation is revoked and its directory deleted. They block no run (they are on the client's
+  own directories, never a run's), but nothing revoked them, so they piled up and resurfaced in listings: a scratch disk held
+  96, from 86 clients, all from the live suites' daemon kills. Revoking them is hygiene.
+- `revoke` (and so `takeOver`), the supervisor's takeover in `ensureRunning` (an orphaned holder or an expired lease), and
+  `deleteRunTree` now also revoke those private-directory delegations, from the same listing, and only for the clients they
+  are already revoking on the run: never as a sweep. One `Disk.exec` (`stat`) confirms each inode is the client's own private
+  directory, and a client that holds anything else (it may hold another run) keeps everything but the run's delegation.
+  Best effort: without `exec`, or when it or a revoke fails, they stay, and the run's revoke never fails for them. The run's
+  own delegations, which every count and decision uses, are unchanged, and `revoke` still returns only those.
+- `revokeBestEffort` revokes what `revoke` revokes and skips every revoke that fails (`revoke` stops at the first); only the
+  listing can fail it. `deleteRunTree` uses it, and the live suites' cleanups revoke through it (by path or by inode, and the
+  holders' private directories) before they delete a run's tree; the Docker, Daytona and lifecycle suites matched by path
+  only. The run suite's daemon-kill and host-loss tests check that no delegation of a killed client is left.
+- New exports: `revokeBestEffort`, `revokeCompanions`, `companionsOf`.
+- **`beforeResume`: an awaited step before the run resumes**
+  - `openDurableRun` and an app (`AppOptions`) take an optional `beforeResume(run)`, awaited once per incarnation after the
+    Harness is open (its registry installed) and the run is live, and before the Harness resumes. No resumed task takes a
+    step until it settles, and what it admits (a submission, a write) is committed before anything a resumed task's steps
+    commit. It sees the open Harness, the open's context, the generation, the run record and the claim.
+  - It also gets the store the Harness was opened over, read-only, and its head: `storage` has `scanConversations`,
+    `scanTasks`, `scanDocuments` and `document` on a frozen object of its own, with no `commit` or `mintId` even through a
+    cast, and `head` is the store's last committed sequence once the Harness is open. A recorder snapshots every document
+    at `head` in the hook; until the hook commits, the current state is the state at `head`, which is how a document that
+    keeps no history (`latest`, session and task documents) reads.
+  - Use: a host reconciling what a resumed tool depends on (a browser, a mount) before the task that uses it continues;
+    `onStep` cannot, since it is synchronous and gets no Harness.
+  - A rejection fails the open like any open step (`before-resume`), and the claim is released.
+  - New exports: the `BeforeResume` and `StoreReads` types.
+- **`localRun(root)`: a run on a plain local directory, one machine**
+  - New export `localRun(root)` returns `openDurableRun`'s `acquire` and `claimDir` for a run in a directory of this
+    machine: the claim is the directory (made when missing), with no mount; `claimDir` is `openClaimDir(root, { fstype:
+    null })`. Its barrier refuses once fenced and syncs nothing (SQLite makes the store's commits durable; `work/` is the
+    OS's to flush). It is for one machine and says so: only the owner lock keeps a second process off the run.
+  - `mountToken` is optional: required only with the default `acquire` (refused with `INVALID_ARGUMENT` before anything
+    mounts when missing); a replaced `acquire` is handed an empty token.
+  - A local run needs Linux, for now, and the README says why: the run's root is held open through `/proc/self/fd`
+    (`openClaimDir`), and the default environment needs `setpriv` (`noNewPrivs`) and `/proc/self/fd` (`confineFiles`).
+    macOS has neither.
+- Installs beside pi-durable 1.2: the peer ranges of `@earendil-works/pi-durable` and `@earendil-works/chord` widen to `>=1.0.4 <1.3.0`, so the package installs beside 1.0.4, 1.1 and 1.2. It is still developed against 1.1.0; CI runs its whole suite at 1.2.0 (`pi-1-2`) and at 1.0.4 (`pi-durable-disk-pi-floor`).
+  - pi-durable 1.2 reads a tool result's `output` and sends the model an empty result for one that says `content`, with no error (1.0.4 and 1.1 read `content`). The package's own source builds no tool result. The test apps' tools (the lifecycle app, the acceptance app, the live instance) and the paid-effect example give their text through `api.output()` and name neither key, which every version reads; tests assert the model gets a tool's text, not an empty result.
+  - pi-durable 1.2 fails a Session on any error a `Storage` throws, except its own `StorageRequestError` (an invalid request) and a read its caller cancelled. The store is pi's `SqliteStorage` behind the fenced database and the lease's commit observer, neither of which rewraps an error, so an invalid read (a cursor that is not one, an unknown conversation) fails only that call. A fenced commit still fails the Session: on 1.2 later operations refuse with `SessionFailed`, its `cause` the fenced error, where 1.0.4 and 1.1 said the Session was poisoned.
+  - pi-durable 1.2's `bash` answers a nonzero exit with an error result where 1.0.4 and 1.1 threw. The workspace barrier runs after it either way, with the command's writes on disk before the error result commits.
+  - The floor job measured a mixed family: its install left pi-durable 1.0.4 at the root loading chord and pi-ai 1.1.0, and the version guard checked only what the package resolved. The guard now also checks chord and pi-ai as the installed pi-durable loads them, and reads `PI_EXPECT_VERSION` beside `PDA_EXPECT_PI_DURABLE`; the job installs one copy of each family package through `scripts/pi-leg.mjs`.
+  - The test helpers that signal a process (`killQuietly`, `alive`) refuse a pid of 0 or below: a test that never learned its child's pid passed 0 from its `finally`, and `kill(0)` signalled the test runner's whole process group. A test removes a directory a run still writes into without racing its heartbeat (from #251).
+- `@parcha/pi-durable-disk/lease` exports the four types its own signatures name: `AcquireOptions`, `PersistRecord` and `ClaimDir` (in `OpenRunLeaseOptions`) and `Unmounted` (in `Claim`). A host that imports only this entry can now write the type of every option it passes to `openRunLease`. They are type-only exports, so the entry's bundle still leaves out the supervisor, the host drivers, the CLI and the app contract. A test checks that every type of the package the entry's declarations name is exported by the entry.
+- **A run on a local directory ends the commands a killed instance left running, before it resumes**
+  - pi makes each command the leader of its own process group, so a SIGKILL of the instance does not reach its commands,
+    and a local run has no unit cgroup to end them: a command kept running, and writing in `work/`, beside the next
+    incarnation. Now a local run's environment marks each command it starts (`PI_DURABLE_DISK_COMMANDS=<its token>` in the
+    command's environment) and records each of its commands' groups (the leader and every descendant it has seen, each by
+    pid, start ticks and boot) under `<root>/commands/`: another environment's commands in the same process, or the app's
+    own detached helpers, are never its to record. Each walk follows every recorded process still alive, so a background
+    worker whose leader exited, and the children it starts later, are recorded too, and the next open, holding the owner lock, kills what is
+    still the recorded process, waits until it is gone and clears the records, before the Harness opens (a new open step,
+    `commands`, after `layout`).
+  - A kill reaches a process only when its pid, start ticks and boot all match a record, and never pid 1 or below
+    (`kill(-1)` would reach every process the user may signal), the opening process or its group. Only the instance writes records; a command that forged one could already kill what it names (it runs as
+    the same user, or with `runAs` cannot write the instance's 0700 directory), so a record grants nothing.
+  - What is still alive at the reap's deadline (a process in an uninterruptible wait, or one it may not signal) refuses the
+    open: `HeldError` with holder `commands` (`COMMANDS_ALIVE`, exit 76), naming each pid and its command line and saying
+    what to do (end them, then open the run again). The run never resumes beside it, its record stays, and the next open
+    tries again. A record that cannot be written (a full disk) is said once on
+    stderr and the recorder keeps trying. A command started within the last walk's interval (about 0.1 s) before the kill
+    can be missed.
+  - A claim opts in with `Claim.commands` (the directory); `localRun`'s claim sets it. A mount's run is unchanged: its host
+    ends commands with the unit's cgroup or the container.
+- **Stopping an instance never signals pid 1 or below, whatever its handle or state file says, nor does the lease watchdog**
+  - `localHost`'s `stop` of a development-mode (`child`) handle signals the handle's pid as a group. A handle comes back
+    from `run.json` with whatever was written there: pid 1 with pid 1's real start ticks made it `kill(-1)`, every process
+    the supervisor's user may signal, and pid 0 (or a pid that is not an integer) with no start ticks made it `kill(-0)`,
+    the supervisor's own group. It now signals only an integer pid above 1 whose handle carries start ticks.
+  - The Daytona launcher's `stop` had the first of those: a state file naming pid 1 with its real start ticks made it
+    SIGTERM pid 1 and `kill(-1, SIGKILL)`. Its liveness check now takes only an integer pid above 1 with start ticks.
+  - The lease watchdog's sweep killed a direct child's process group unless it was the instance's own or 0 and below; a
+    child in group 1 (possible in a container whose init's group is in the instance's session) made it `kill(-1)`. A
+    child in group 1 is now killed alone.
+- **A tool may write in the temp directory it was given**
+  - `archilEnv`'s confinement made all of `<root>/tmp/` read-only to file operations, including the directories its own
+    `createTempDir` (and `createTempFile`) hands out, so a tool that writes into the temp dir it asked for was refused
+    `outside_work`: pi-vision's `read` of any media file failed on a disk run. A directory `createTempDir` returns is now
+    writable, for the run's environments; the rest of `tmp/` (another run's directories, `tmp/` itself) stays read-only.
+  - The tool may remove that directory (`env.remove`, as vision does when it is done), and its grant goes with it.
+  - It is made through a held handle of `tmp/` that does not follow a link, and granted by name under the canonical `tmp/`:
+    a `tmp/` a command replaced with a link is refused, and a directory swapped for a link grants nothing beyond itself.
+- **The self-fence watchdog starts in a host launched with `--input-type=module`**
+  - The watchdog's worker is eval'd CommonJS and inherited the host's Node flags. Under `--input-type=module` (a host that
+    runs inline ESM through `-e` or stdin) Node read it as ESM, it threw `require is not defined`, and the run died at
+    open. The worker now starts with no inherited flags (`execArgv: []`); it needs none of the host's.
+- An example's test can no longer hang past its timeout: `runExample` waits for the example's output only until the timeout
+  and a 2 s grace, then drops the pipes a process outside the example's group still holds and reports the run as timed out.
+  The package's tests run with `--test-timeout=240000`, so a test that hangs fails with its name.
+- **An example, `audit-across-crashes`: the store is the record**
+  - A run on a local directory is killed twice in the middle of a tool call. A recorder in `beforeResume` snapshots every
+    task, document and transcript entry at each incarnation's `head`, and the example prints a per-generation account (who
+    asked what, who answered, which calls were cut and which generation settled them as `interrupted`) read from those
+    snapshots alone. No disk, no key: `node examples/audit-across-crashes/main.ts` after the build, with pi-ai's faux model.
+    A test runs it in `npm test`.
+- **An examples index and the conventions every new example follows**
+  - `examples/README.md` lists the examples with what each shows, what it needs, and whether CI runs it, and states how a
+    new one is written: one directory and one property per example, self-contained imports, `node examples/<name>/main.ts`
+    on a local directory with pi-ai's faux model (no key, no network), one closing `ok: ...` line, and a test under
+    `test/examples/` that runs it on every change.
+  - `test/examples/conventions.test.ts` checks what code can: each example's files, its imports (read from the parse tree),
+    its test and its row in the index. `test/examples/_run-example.ts` runs an example from a scratch directory as its own
+    process group and reaps the group whatever ends it, and `assertExampleOk` fails a run that exited 0 while a
+    process it started still held its output; the quickstart's test uses both.
+- **A quickstart on one machine: no disk, no key**
+  - The README opens with a durable chat on a directory of this machine (`localRun`) and pi-ai's faux model: one process
+    is killed (`SIGKILL`) after its third answer, a second opens the same run and answers the rest, and the transcript read
+    back from the store has every message answered once. It is `examples/01-durable-chat/on-a-directory.mjs`.
+  - The stranger test installs the packed package and its peers in an empty directory, runs the README's script and
+    expects that line, so the quickstart a reader copies is the one that is checked.
+- The README's bundle sizes for the two entries are re-measured: about 60 KB for `@parcha/pi-durable-disk/lease` against about 620 KB for the root entry (it said 52 KB and 493 KB), with the esbuild command that produces them.
+- **The README starts with a path chooser and states how a run on a local directory fails**
+  - "Choose your path" maps what a reader has (Linux and Node only, Docker and an Archil account, a Linux host with FUSE, an
+    app of their own) to the quickstart or section to start with, and points to the examples index.
+  - The failure table gains the rows for a run on a local directory (`localRun`): a crash or SIGKILL (the next open ends
+    the commands the killed instance left running, then resumes), a power loss (the store holds, `work/` may be older), a
+    second process on the machine (refused, exit 76), a process of the killed incarnation that will not die (the open is
+    refused, exit 76, naming it), and another machine reaching the directory (unsupported: no fence).
+    The layout names a local run's `commands/`.
+
 ## 0.1.0-beta.12, 2026-10-09
 
 Renamed from `@parcha/pi-durable-archil`. The package is now `@parcha/pi-durable-disk` and its command is `pi-durable-disk`, for branding:

package/README.md

@@ -14,6 +14,18 @@ release names no other backend and promises none.
 pi-durable assumes two things it does not provide: exactly one live process per store, and a store that outlives the
 machine. A Cloudflare Durable Object gives it both. This package gives it both on an Archil disk you mount on any Linux host.
 
+## Choose your path
+
+| You have | Start with | What you see |
+|---|---|---|
+| Linux and Node 22.19 or later, nothing else | [Quickstart on one machine](#quickstart-on-one-machine-no-disk-no-key) | A durable chat on a directory of this machine, killed with `SIGKILL` and finished by a second process. One machine and no fence: the directory is the claim |
+| Docker (macOS or Linux) and an Archil account | [Quickstart with Docker](#quickstart-with-docker) | A host killed in the middle of a paid charge, and the run resumed on another, every instance in a container |
+| A Linux host with FUSE and an Archil account | [Quickstart on a Linux host](#quickstart-on-a-linux-host-kill-a-host-watch-the-run-resume-on-another), then [Setting up a host for production](#setting-up-a-host-for-production) | The production shape: systemd units, the supervisor, and a lost host's run back in about a second |
+| An app or a host of your own | [The app](#the-app) and [Library](#library) | `openDurableRun`, `localRun`, the supervisor and host drivers, `serve`, parking and `fork` from your code |
+
+[examples/](examples/README.md) lists the examples, one property each, with what each needs: several run with no disk
+and no key.
+
 ## How it maps to a Durable Object
 
 | Durable Object | This package | Supplied by |
@@ -48,10 +60,12 @@ machine. A Cloudflare Durable Object gives it both. This package gives it both o
 - An Archil account, a disk, and an API key for the supervisor, all from the Archil console. Create the disk in the region
   nearest the host (any size; its id looks like `dsk-0123456789abcdef` and its region like `aws-us-east-1`). Hosts and
   instances never hold the API key.
-- `@earendil-works/pi-durable` and `@earendil-works/chord`, `^1.0.4`, as peer dependencies.
+- `@earendil-works/pi-durable` and `@earendil-works/chord`, `>=1.0.4 <1.3.0`, as peer dependencies. The package is developed against 1.1.0, and CI runs its whole suite on 1.0.4 too, the lowest version the range accepts, and on 1.2.
+
+Not covered yet: a Kubernetes host driver (the `HostDriver` interface is below) and running the loop across machines
+where FUSE is unavailable. Without Archil, a run can live on a plain directory of one machine
+([A run on a local directory](#a-run-on-a-local-directory)).
 
-Not covered yet: a Kubernetes host driver (the `HostDriver` interface is below) and running the loop where FUSE is
-unavailable.
 
 ## Install
 
@@ -66,6 +80,114 @@ git clone https://github.com/Parcha-ai/agentrun.git && cd agentrun && npm ci --i
 cd packages/pi-durable-disk
 ```
 
+## Quickstart on one machine: no disk, no key
+
+The fastest look, on Linux with Node 22.19 or later: a durable chat on a directory of this machine, with
+[`localRun`](#a-run-on-a-local-directory) instead of a disk and pi-ai's faux model instead of a key. One process answers the
+first messages and is killed (`SIGKILL`) after its third answer; a second opens the same run and answers the rest, and the
+transcript, read back from the store, has every message answered once. The directory is the claim, so this guards one
+machine only; the quickstarts below put the run on a disk that outlives the machine.
+
+In an empty directory, install the package and its peers, save this as `chat.mjs`
+(it is [examples/01-durable-chat/on-a-directory.mjs](examples/01-durable-chat/on-a-directory.mjs)):
+
+```sh
+npm install @parcha/pi-durable-disk@beta @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
+```
+
+```js
+// A durable chat on a directory of this machine: no disk, no key (pi-ai's faux model answers). One process answers the
+// first messages and is killed (SIGKILL) after its third answer; a second opens the same run and answers the rest, and
+// the transcript, read back from the store, has every message answered once. One machine: the directory is the claim.
+import { spawn } from "node:child_process";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { BACKGROUND_CONTEXT as ctx } from "@earendil-works/chord/context";
+import { createModels, fauxAssistantMessage, fauxProvider } from "@earendil-works/pi-ai";
+import { createRegistry } from "@earendil-works/pi-durable";
+import { localRun, openDurableRun } from "@parcha/pi-durable-disk";
+
+const MESSAGES = ["Where does your transcript live?", "What happens if this process is killed now?", "Who answers after that?", "What was my first question?", "Are you the same process?", "Say goodbye."];
+const root = join(process.cwd(), "chat-run");
+const text = (message) => (typeof message.content === "string" ? message.content : message.content.map((part) => part.text ?? "").join(""));
+
+if (process.argv[2] === "instance") {
+  let generation = 0;
+  const faux = fauxProvider();
+  faux.setResponses(Array.from({ length: 100 }, () => (context) => {
+    const asked = context.messages.filter((message) => message.role === "user");
+    return fauxAssistantMessage(`Answer ${asked.length}, by generation ${generation}: "${text(asked.at(-1))}"`);
+  }));
+  const models = createModels();
+  models.setProvider(faux.provider);
+  const run = await openDurableRun({ disk: "local", region: "local", id: "chat" }, { ...localRun(root), harness: { models, registry: createRegistry() } });
+  generation = run.generation;
+  const model = faux.getModel();
+  const chat = await run.harness.root(ctx, { agent: { model: { provider: model.provider, modelId: model.id } } });
+  const answers = async () => (await chat.entries({}, 100, undefined, ctx)).items.reverse().filter((entry) => entry.kind === "pi.assistant");
+  const before = (await answers()).length;
+  console.log(`generation ${generation} opened the run in ${root} (${before} answered before)`);
+  for (const [i, content] of MESSAGES.entries()) {
+    // The request id makes a message a no-op once it was admitted: a new generation walks the list from the top.
+    await (await chat.submit({ type: "input", content, requestId: `message-${i + 1}` }, ctx)).wait(ctx);
+    if (i >= before) console.log(`generation ${generation} answered message ${i + 1}`);
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  for (const answer of await answers()) console.log(`  ${text(answer.model[0])}`);
+  await run.setStatus("done");
+  await run.release();
+  process.exit(0);
+}
+
+// The supervisor: an instance, killed after its third answer, then another on the same directory (a fresh one each time).
+// It reads whole lines, and waits for `close` (the process gone and all its output read), not `exit`.
+rmSync(root, { recursive: true, force: true });
+const start = () => spawn(process.execPath, [fileURLToPath(import.meta.url), "instance"], { stdio: ["ignore", "pipe", "inherit"] });
+const eachLine = (child, onLine) =>
+  createInterface({ input: child.stdout }).on("line", (line) => {
+    console.log(line);
+    onLine(line);
+  });
+const first = start();
+eachLine(first, (line) => {
+  if (/answered message 3\b/.test(line)) first.kill("SIGKILL");
+});
+await new Promise((resolve) => first.on("close", resolve));
+console.log("the first process was killed (SIGKILL); a second opens the same run");
+const output = [];
+const second = start();
+eachLine(second, (line) => output.push(line));
+const code = await new Promise((resolve) => second.on("close", resolve));
+const answered = output.flatMap((line) => {
+  const match = /^ {2}Answer (\d+), by generation (\d+)/.exec(line);
+  return match ? [{ n: Number(match[1]), generation: Number(match[2]) }] : [];
+});
+const once = MESSAGES.every((_, i) => answered.filter((a) => a.n === i + 1).length === 1) && answered.length === MESSAGES.length;
+const generations = [...new Set(answered.map((a) => a.generation))].sort();
+if (code !== 0 || !once || generations.length < 2) {
+  console.error(`not ok: exit ${code}, answers ${JSON.stringify(answered)}`);
+  process.exit(1);
+}
+console.log(`ok: ${MESSAGES.length} messages answered once each, by generations ${generations.join(" and ")}, from the store in ${root}`);
+```
+
+Then run it (about five seconds; it writes the run under `./chat-run/`):
+
+```sh
+node chat.mjs
+```
+
+It ends with:
+
+```
+  Answer 1, by generation 1: "Where does your transcript live?"
+  ...
+  Answer 6, by generation 2: "Say goodbye."
+ok: 6 messages answered once each, by generations 1 and 2, from the store in <this directory>/chat-run
+```
+
 ## Quickstart with Docker
 
 You need Docker (Docker Desktop, OrbStack or Colima on macOS, Docker Engine on Linux), Node 22.19 or later, and an Archil
@@ -140,7 +262,7 @@ Each example's README lists the exact commands the demo runs, so you can run the
 
 An instance is `pi-durable-disk run --app <module> ...`: `openDurableRun` with the app's options. The module is an ES
 module whose default export is a function of where the run lives and returns pi's Harness options without `env` (the run
-builds `env` on its claim: the workspace is `<root>/work`), plus an optional `onOpen`:
+builds `env` on its claim: the workspace is `<root>/work`), plus an optional `beforeResume` and an optional `onOpen`:
 
 ```ts
 import { BACKGROUND_CONTEXT as ctx } from "@earendil-works/chord/context";
@@ -159,6 +281,10 @@ export default async function app(where: AppContext): Promise<AppOptions> {
   return {
     models,
     registry,
+    async beforeResume({ harness, context, generation }) {
+      // Awaited once per incarnation, after the Harness is open and before it resumes: no resumed task takes a step
+      // until this settles, and what it admits commits before their steps do. Reconcile here what a resumed tool depends on.
+    },
     async onOpen(run) {
       // Called once per incarnation, after the run is open and resumed. run.generation is 1 on a first start and
       // higher on every resume. run.harness is pi-durable's Harness.
@@ -176,7 +302,11 @@ rerun. Any other tool is an effect: its intent is committed before it starts, an
 was `interrupted`, never run again. `run.setStatus("done" | "failed" | "paused" | "sleeping", detail)` records the run's
 status in `run.json`; `done` and `failed` run the durability barrier first. `run.release()` closes the Harness, kills the
 run's commands, runs the barrier, seals `run.json` with the store's last sequence, and unmounts. A module that is missing
-or throws, or an `onOpen` that rejects, is `AppError` (exit 1, which the unit retries).
+or throws, or an `onOpen` that rejects, is `AppError` (exit 1, which the unit retries). A `beforeResume` that rejects
+fails the open (its step is `before-resume`) and releases the claim. Besides the Harness, the hook gets `storage`, the
+store the Harness was opened over as four reads (`scanConversations`, `scanTasks`, `scanDocuments`, `document`) with no
+way to a write, and `head`, the store's last committed sequence: a recorder snapshots every document at `head` there.
+Until the hook commits, the current state is the state at `head`, which is how a document that keeps no history reads.
 
 ## The CLI
 
@@ -409,10 +539,22 @@ mount token reaches the journal, and that nothing is left behind. It needs syste
 | A second instance on the same host | The owner lock (an exclusive SQLite lock on `owner.lock`) is refused, exit 76 | none |
 | Two supervisors race | The mount admits one claimant; the other instance exits 76 | none |
 | The control API lists the run's holder without a path (it resolves paths best-effort) | The supervisor maps pathless delegations' inodes to run directories with one `Disk.exec` per pass (`find -inum`) and counts one on the run's directory as the run's: a live one keeps the run healthy, an orphaned one is revoked and the run restarted. Where `exec` is unavailable or fails, the pass is `CONTROL_API_FAILED` and starts nothing (the supervisor never forces); a dead holder then stays until Archil lists its path again or an operator revokes it by client and inode | no second instance; nothing started over a holder it cannot see |
+| A client dies holding its own private directories (`.archil/client-<clientId>` and its `unlinked/`, which the control API lists with no path and on no run directory) | They block no run. Every revoke that fences or deletes a run (`revoke`, `takeOver`, the supervisor's takeover, `deleteRunTree`) also revokes, from the same listing, the private-directory delegations of the clients it revokes on the run, confirmed by one `Disk.exec` (`stat`), unless the client holds anything else; best effort, so one left stays for an operator to revoke by client and inode | none: they hold no run directory |
 | The store is behind its `run.json` seal | `STORE_BEHIND_SEAL`: `run.json` is marked failed and the instance exits 65; the supervisor does not restart it | none started |
 | SIGTERM (a deploy) | The instance stops taking submissions and drains for up to `--drain-timeout`, writes `sleeping` with its wake (now; the deadline when everything only waits; null when idle and woken by requests), then closes, kills its commands, barriers, seals and unmounts, exit 0; the supervisor starts it again at the wake | work cut at the drain's deadline resumes on the next open: safe tools rerun, unsafe ones report the interruption |
 | Everything the run does is a retry or poll wait longer than the park threshold | The instance writes `sleeping` with `wakeAt` (the deadline), releases and exits 0; the supervisor starts it at `wakeAt` and pi's timer sleeps whatever is left; a `run.json` write that fails is a fence (exit 75) and the lease path resumes the run | nothing is lost: the wait is a checkpoint in the store |
 
+**On a local directory** (`localRun`) nothing is mounted or delegated and no supervisor watches the run, so the rows above
+about revocation, takeover and the lease's replacement do not apply. These do:
+
+| Failure | What happens | Effects |
+|---|---|---|
+| The instance crashes or is SIGKILLed | Its owner lock goes with the process. The next open of the directory (by the app, or whatever restarts it) takes the run, ends the commands the killed incarnation left running (its `commands` step, before the Harness opens), and `resume()`s from the last commit | running tasks go back to pending; effects in flight are `interrupted`, never rerun; no command of the killed incarnation still runs once the run resumes. pi makes each command the leader of its own process group, so the SIGKILL does not reach them and a local run has no unit cgroup: the instance records each command's group under `commands/` (by pid, start ticks and boot) and the next open kills what still matches. A command started within about 0.1 s before the kill can be missed |
+| A process the killed incarnation's commands started does not die at the next open (an uninterruptible wait, or one the run's user may not signal) | The open is refused: `HeldError` `COMMANDS_ALIVE`, exit 76, naming each pid and its command line; the records stay | none: the run does not resume beside it. End those processes (`kill -9` as their owner, or wait for them) and open the run again |
+| Power loss or an OS crash | The store's commits are durable (SQLite at `synchronous = FULL`); `work/` is the operating system's to flush, since the claim's barrier syncs nothing | the store resumes from its last commit; files the agent wrote in `work/` can be older than what the store recorded |
+| A second process opens the run on this machine | The owner lock is refused (`HeldError`, exit 76) | none |
+| A process on another machine reaches the directory (a network share) | Nothing stops it: a local directory has no fence | unsupported, since two writers can corrupt the store. A directory another machine can reach needs a disk with a claim and a fence |
+
 What a revoke cannot do: no fence reaches a third party. A paid API that already has a request has it. The package
 guarantees that this runtime does not start an effect twice; an effect your model decides to retry is a new call, so give a
 paid API an idempotency key from your own business key.
@@ -442,7 +584,8 @@ to 6.3 s with a 6 s test lease (90 to 120 s with the defaults).
 - **The file tools stay inside `work/`.** pi's `read`, `write` and `edit` run in the loop's process, not in a command
   sandbox, so every file operation of the environment resolves its path to the file the kernel would reach (`..`, absolute
   paths, symlinks, dangling links, a missing tail) and refuses it unless it lies in `work/` (reads may also use `tmp/`, where
-  the bash tool tells the model its long output went, and `readRoots` the app names). An agent cannot `write
+  the bash tool tells the model its long output went, and `readRoots` the app names; writes may also go inside a directory
+  the environment's `createTempDir` returned, for the tool it was handed to). An agent cannot `write
   ../store/run.sqlite`, `../run.json` or `../owner.lock`: the call fails with a `PathOutsideWorkError` the model sees as
   a failed tool result. A path is opened one component at a time from a held handle of `work/`, without following links,
   so a link a command swaps in after the check is refused too. This covers the file tools only; a command still runs as
@@ -473,6 +616,9 @@ to 6.3 s with a 6 s test lease (90 to 120 s with the defaults).
   tmp/                     pi's temp files and long-output spills, so a path a result names still exists after a takeover
 ```
 
+A run on a local directory (`localRun`) has the same layout, plus `commands/`: the process groups of the commands its
+instance started, which the next open ends before it resumes (a local run has no unit cgroup to end them).
+
 The mountpoint is the same absolute path on every host of a deployment, so paths inside the run are identical wherever
 it resumes.
 
@@ -484,9 +630,9 @@ its objects, and remove its token users (`supervise --id ID --sweep-tokens --tok
 
 **Revoke before you delete.** Deleting the objects of a run through the S3 API while a delegation on the path is still
 held, even an orphaned one left by a killed host, does not take effect: the same run id came back with its old store when a
-supervisor next started it. `deleteRunTree(control, id)` does it in order: it revokes the run's delegations, deletes, and
-requires the prefix to be empty. Doing it by hand, revoke the delegation first, delete, then list the prefix and check it is
-empty.
+supervisor next started it. `deleteRunTree(control, id)` does it in order: it revokes the run's delegations and its holders' private directories,
+deletes, and requires the prefix to be empty. Doing it by hand, revoke first (`revoke(control, id)` takes the same set), delete,
+then list the prefix and check it is empty.
 
 ## Library
 
@@ -502,8 +648,35 @@ A host that owns its own pi-durable Harness and store connections imports the na
 self-fence, the seal and the release, without a store or a Harness), `storeHead`, the store's fence and pragma helpers
 (`Fence`, `FencedDatabase`, `assertPragmas`, `PROFILE_PRAGMAS`, `openArchilStore`), and the typed errors and exit codes. It
 leaves out the supervisor, the host drivers, the CLI and the app contract, and the package declares `"sideEffects": false`, so
-a bundler keeps only what you use: a bundle of the app with `await import("@parcha/pi-durable-disk/lease")` is about 52 KB
-minified against about 493 KB for `await import("@parcha/pi-durable-disk")` (measured with esbuild, pi-durable inlined).
+a bundler keeps only what you use: a bundle of the app with `await import("@parcha/pi-durable-disk/lease")` is about 60 KB
+minified against about 620 KB for `await import("@parcha/pi-durable-disk")` (esbuild `--bundle --minify --platform=node
+--format=esm`, which inlines pi-durable, chord and their dependencies).
+
+### A run on a local directory
+
+`localRun(root)` returns the `acquire` and `claimDir` that put a run on a plain directory of this machine, with no mount
+and no mount token:
+
+```ts
+import { localRun, openDurableRun } from "@parcha/pi-durable-disk";
+
+const run = await openDurableRun({ disk: "local", region: "local", id: "run-1" }, {
+  ...localRun("/var/runs/run-1"),          // made when it is missing; work/ and store/ inside it
+  harness: { models, registry },
+});
+```
+
+It is for one machine (a laptop, a CI job, a test), and says so: the claim is the directory itself, so nothing but this
+machine's owner lock keeps a second process off the run (a second open while one holds it is refused), and nothing at
+all keeps out a process on another machine that can reach the directory. Its barrier refuses once the run is fenced,
+like a mount's, but syncs nothing: the store's commits are made durable by SQLite, and the files the agent wrote in
+`work/` are the operating system's to flush, so a power loss can lose what it had not written yet. `mountToken` is
+required only with the default `acquire`; without either, the open is refused (`INVALID_ARGUMENT`) before anything mounts.
+
+It needs Linux, for now. The run's root is held open through `/proc/self/fd` (`openClaimDir`), and the default
+environment confines commands with `setpriv` (util-linux, `noNewPrivs`) and the file tools through `/proc/self/fd`
+(`confineFiles`). macOS has neither, and turning the environment's two off does not help: the open still holds the root
+through `/proc/self/fd`. A portable claim directory is what a local run on macOS would need.
 
 ## Tests
 

package/dist/app.d.ts

@@ -11,6 +11,11 @@ export interface AppContext {
 }
 /** pi's HarnessOptions without `env` (registry, models, settings, conversationCreated, now, onReport), plus the hooks below. */
 export type AppOptions = OpenDurableRunOptions["harness"] & {
+    /**
+     * Awaited once per incarnation after the Harness is open and before it resumes (`OpenDurableRunOptions.beforeResume`):
+     * no resumed task takes a step until it settles. A rejection fails the open (exit 1, retried).
+     */
+    beforeResume?: OpenDurableRunOptions["beforeResume"];
     /**
      * Called once per incarnation after the run is open and resumed; `run.generation` tells a first start from a resume.
      * Work that must keep the instance up belongs in pi's tasks and tools: parking sees only those.

package/dist/app.js

@@ -8,8 +8,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // The app an instance hosts (`pi-durable-disk run --app <module>`): an ES module whose default export is a function
 // of where the run lives that returns pi's Harness options (without `env`, which the run builds on its claim), an
-// optional `onOpen` for the app to submit or resume work once the run is open and resumed, how `serve` creates the root
-// conversation, and how a parking run records its wake.
+// optional `beforeResume` for what must settle before the run resumes, an optional `onOpen` for the app to submit or
+// resume work once the run is open and resumed, how `serve` creates the root conversation, and how a parking run records
+// its wake.
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { PdaError } from "./errors.js";

package/dist/claim.d.ts

@@ -92,6 +92,12 @@ export interface Claim {
     readonly fenced: boolean;
     /** Mark the claim lost (the store's facade calls this on an I/O-class error); later barriers throw at once. */
     markFenced(cause?: unknown): void;
+    /**
+     * Where the run's environment records the commands it starts, so that the next open of this claim ends what a killed
+     * incarnation left running (`reapCommands`, before the Harness opens). Set by a claim that nothing else cleans up after,
+     * as a local run's; a mount's host ends them with its unit's cgroup or its container.
+     */
+    readonly commands?: string;
     /** `archil sync`: every pending write on the mount is durable when it resolves. A failure fences the claim. */
     barrier(): Promise<{
         ms: number;
@@ -174,8 +180,29 @@ export type PathlessResolver = (pathless: readonly Delegation[]) => Promise<Read
  * removes them.
  */
 export declare function pathlessResolver(control: Pick<ControlApi, "exec">): PathlessResolver;
-/** Revoke every delegation on the run through the control API. The old holder's next fsync returns EIO. */
+/**
+ * The delegations `held`'s clients also hold on their own private directories (`privateDirs`: inode to the client whose
+ * private directory it is). A killed client leaves them orphaned, and nothing ties them to a run: they block no run, but
+ * they pile up and resurface in listings. A client that holds anything else beyond `held` may hold another run, so none
+ * of its delegations is a companion.
+ */
+export declare function companionsOf(all: readonly Delegation[], held: readonly Delegation[], privateDirs: ReadonlyMap<number, string>): Delegation[];
+/**
+ * Revoke the companions of `held` (`companionsOf`): only for clients the caller is already revoking because it fences or
+ * deletes a run, never as a sweep. From `all` or a fresh listing. Best effort, and hygiene only: a companion blocks no
+ * run, so one left behind (or a failed listing or `exec`) costs a listing entry. Returns the ones revoked.
+ */
+export declare function revokeCompanions(control: Pick<ControlApi, "listDelegations" | "revokeDelegation" | "exec">, held: readonly Delegation[], all?: readonly Delegation[]): Promise<Delegation[]>;
+/**
+ * Revoke every delegation on the run through the control API, then its holders' private directories
+ * (`revokeCompanions`). The old holder's next fsync returns EIO. Returns the run's own delegations.
+ */
 export declare function revoke(control: ControlApi, id: string): Promise<Delegation[]>;
+/**
+ * Revoke what `revoke` revokes, skipping every revoke that fails: for cleanup, where deleting the tree next checks what
+ * is left. Only the listing (and a pathless resolution) can fail it. Returns the run's own delegations.
+ */
+export declare function revokeBestEffort(control: Pick<ControlApi, "listDelegations" | "revokeDelegation" | "exec">, id: string): Promise<Delegation[]>;
 /** Revoke through the control API, then mount plainly; if the API path fails, mount with `--force`. */
 export declare function takeOver(control: ControlApi, opts: AcquireOptions): Promise<Claim>;
 /**

package/dist/claim.js

@@ -195,18 +195,89 @@ async function runDirsByInode(control, inodes) {
     }
     return names;
 }
-/** Revoke every delegation on the run through the control API. The old holder's next fsync returns EIO. */
+/** A client's private directories on the disk: `.archil/client-<clientId>` and its `unlinked/`. */
+const PRIVATE_DIR = /^\/*\.archil\/client-([A-Za-z0-9_-]+)(\/unlinked)?$/;
+/**
+ * The delegations `held`'s clients also hold on their own private directories (`privateDirs`: inode to the client whose
+ * private directory it is). A killed client leaves them orphaned, and nothing ties them to a run: they block no run, but
+ * they pile up and resurface in listings. A client that holds anything else beyond `held` may hold another run, so none
+ * of its delegations is a companion.
+ */
+export function companionsOf(all, held, privateDirs) {
+    const clients = new Set(held.map((d) => d.clientId));
+    const listed = new Set(held.map((d) => `${d.clientId}/${d.inodeId}`));
+    const others = all.filter((d) => clients.has(d.clientId) && !listed.has(`${d.clientId}/${d.inodeId}`));
+    const own = (d) => (d.path ? PRIVATE_DIR.exec(d.path)?.[1] : privateDirs.get(d.inodeId)) === d.clientId;
+    const holdsMore = new Set(others.filter((d) => !own(d)).map((d) => d.clientId));
+    return others.filter((d) => !holdsMore.has(d.clientId));
+}
+/** The inodes of `clients`' private directories, by one `exec` (`stat`); none without `exec`. */
+async function privateDirInodes(control, clients) {
+    const asked = clients.filter((c) => /^[A-Za-z0-9_-]+$/.test(c));
+    const dirs = new Map();
+    if (!control.exec || asked.length === 0)
+        return dirs;
+    const paths = asked.flatMap((c) => [`.archil/client-${c}`, `.archil/client-${c}/unlinked`]);
+    const r = await control.exec(`stat -c '%i %n' -- ${paths.join(" ")} 2>/dev/null; true`);
+    for (const line of String(r.stdout ?? "").split("\n")) {
+        const m = /^(\d+) (\S+)$/.exec(line);
+        const client = m && PRIVATE_DIR.exec(m[2])?.[1];
+        if (m && client && asked.includes(client))
+            dirs.set(Number(m[1]), client);
+    }
+    return dirs;
+}
+/**
+ * Revoke the companions of `held` (`companionsOf`): only for clients the caller is already revoking because it fences or
+ * deletes a run, never as a sweep. From `all` or a fresh listing. Best effort, and hygiene only: a companion blocks no
+ * run, so one left behind (or a failed listing or `exec`) costs a listing entry. Returns the ones revoked.
+ */
+export async function revokeCompanions(control, held, all) {
+    if (held.length === 0)
+        return [];
+    const listing = all ?? (await control.listDelegations().catch(() => []));
+    const clients = [...new Set(held.map((d) => d.clientId))];
+    const listed = new Set(held.map((d) => `${d.clientId}/${d.inodeId}`));
+    if (!listing.some((d) => clients.includes(d.clientId) && !listed.has(`${d.clientId}/${d.inodeId}`)))
+        return [];
+    const dirs = await privateDirInodes(control, clients).catch(() => new Map());
+    const revoked = [];
+    for (const d of companionsOf(listing, held, dirs)) {
+        await control.revokeDelegation({ clientId: d.clientId, inodeId: d.inodeId }).then(() => revoked.push(d), () => { });
+    }
+    return revoked;
+}
+/**
+ * Revoke every delegation on the run through the control API, then its holders' private directories
+ * (`revokeCompanions`). The old holder's next fsync returns EIO. Returns the run's own delegations.
+ */
 export async function revoke(control, id) {
     const path = runPath(id);
+    let all;
+    let held;
     try {
-        const held = await findDelegations(control, id);
+        all = await control.listDelegations();
+        held = await matchDelegations(all, id, pathlessResolver(control));
         for (const d of held)
             await control.revokeDelegation(d);
-        return held;
     }
     catch (err) {
         throw new ClaimError("CONTROL_API_FAILED", `revoking ${path} failed`, { cause: err });
     }
+    await revokeCompanions(control, held, all);
+    return held;
+}
+/**
+ * Revoke what `revoke` revokes, skipping every revoke that fails: for cleanup, where deleting the tree next checks what
+ * is left. Only the listing (and a pathless resolution) can fail it. Returns the run's own delegations.
+ */
+export async function revokeBestEffort(control, id) {
+    const all = await control.listDelegations();
+    const held = await matchDelegations(all, id, pathlessResolver(control));
+    for (const d of held)
+        await control.revokeDelegation({ clientId: d.clientId, inodeId: d.inodeId }).catch(() => { });
+    await revokeCompanions(control, held, all);
+    return held;
 }
 /** Revoke through the control API, then mount plainly; if the API path fails, mount with `--force`. */
 export async function takeOver(control, opts) {

package/dist/cli.js

@@ -232,7 +232,7 @@ async function runInstance(values) {
         log("app failed", { code: err.code, message: err.message });
         return exitCodeFor(err);
     }
-    const { onOpen, root: rootOptions, wake: appWake, ...harness } = app;
+    const { onOpen, beforeResume, root: rootOptions, wake: appWake, ...harness } = app;
     const holder = JSON.parse(process.env.PDA_HOLDER ?? "{}");
     const cgroup = watchdogOwnsCgroup(holder);
     if (cgroup.warning)
@@ -261,6 +261,7 @@ async function runInstance(values) {
             ownCgroup: cgroup.owns,
             lease: Object.fromEntries(Object.entries(lease).filter(([, v]) => v !== undefined)),
             onStep: (step, t) => void (steps[step] = Math.round(t)),
+            ...(beforeResume ? { beforeResume } : {}),
         });
     }
     catch (err) {