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

package/dist/run.d.ts

@@ -1,6 +1,6 @@
 import type { Context, JsonValue } from "@earendil-works/chord";
 import { Harness } from "@earendil-works/pi-durable";
-import type { HarnessOptions, Storage, ToolRegistration } from "@earendil-works/pi-durable";
+import type { HarnessOptions, Seq, Storage, ToolRegistration } from "@earendil-works/pi-durable";
 import type { SqliteDatabase, SqliteExecutor } from "@earendil-works/pi-durable/storage/sqlite";
 import { type AcquireOptions, type ArchilHost, type Claim, type RunRef } from "./claim.js";
 import { FencedError, PdaError } from "./errors.js";
@@ -57,11 +57,15 @@ export interface LeaseOptions {
     /** How often the self-fence timer looks; default 1 s. */
     readonly checkMs?: number;
 }
-export type OpenStep = "acquire" | "owner-lock" | "run.json" | "heartbeat" | "layout" | "store" | "seal" | "harness" | "live" | "resume";
+export type OpenStep = "acquire" | "owner-lock" | "run.json" | "heartbeat" | "layout" | "commands" | "store" | "seal" | "harness" | "live" | "before-resume" | "resume";
 export type ReleaseStep = "close" | "cleanup" | "barrier" | "seal" | "unlock" | "unmount";
 export interface OpenRunLeaseOptions {
-    /** The mount token from the host driver (reusable, 24 h); travels only on the archil wrapper's stdin, never in an environment. */
-    readonly mountToken: string;
+    /**
+     * The mount token from the host driver (reusable, 24 h); travels only on the archil wrapper's stdin, never in an
+     * environment. Required to mount an Archil disk (the default `acquire`); a run whose `acquire` is replaced (a local
+     * directory: `localRun`) needs none, and its `acquire` is handed an empty token.
+     */
+    readonly mountToken?: string;
     /** Default /mnt/archil. */
     readonly mountRoot?: string;
     /** Mount with `--force`: the takeover fallback when the supervisor could not revoke. */
@@ -110,7 +114,43 @@ export interface OpenDurableRunOptions<Tool extends ToolRegistration = ToolRegis
     readonly env?: (claim: Claim) => RunEnv;
     /** Wraps the raw database inside the store's fence (instrumentation, fault injection). */
     readonly decorateStore?: (database: SqliteDatabase) => SqliteDatabase;
+    /**
+     * Awaited once the Harness is open (its registry installed) and the run is live, 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. A host reconciles here what a resumed tool depends on (a browser, a mount). A rejection
+     * fails the open as any step does (`before-resume`), and the claim is released.
+     */
+    readonly beforeResume?: (run: BeforeResume) => void | Promise<void>;
+}
+/**
+ * What `beforeResume` sees: the open Harness, not yet resumed, the open's context, the incarnation it belongs to, and the
+ * store the Harness was opened over with its head (a recorder snapshots every document at `head` here).
+ */
+export interface BeforeResume {
+    readonly harness: Harness;
+    readonly context: Context;
+    readonly generation: number;
+    /** This incarnation's `run.json`, which the open has already written (`running`, this holder, `detail` null). */
+    readonly record: RunRecord;
+    /**
+     * `run.json` as it was before this open wrote over it: how the run was left. After a park it is `sleeping` with its
+     * `wakeAt` and `detail` and the seal its release wrote; after a planned stop, `paused` or `done` with the `detail` it
+     * set; after a crash, `running` with the dead holder and no new seal. On a fork's first open it is the record `fork`
+     * wrote: `paused`, generation 0, `detail.forkedFrom`. Null only when there was no `run.json` (a new run's first open).
+     */
+    readonly previous: RunRecord | null;
+    readonly claim: RunClaim;
+    /** The store the Harness was opened over, read-only: four reads on an object of their own, and no way to a write. */
+    readonly storage: StoreReads;
+    /**
+     * The store's last committed sequence once the Harness is open, read just before the hook runs. Until the hook commits
+     * something, the store's current state is its state at `head`: a document that keeps no history (`latest`, and session
+     * and task documents) reads only at "current", a `rewindable` one at `head` too.
+     */
+    readonly head: Seq;
 }
+/** The reads of a store that `beforeResume` gets. */
+export type StoreReads = Pick<Storage, "scanConversations" | "scanTasks" | "scanDocuments" | "document">;
 /** The claim as the app sees it: paths, the fenced flag, and a barrier whose failure fences the run. */
 export interface RunClaim {
     readonly ref: RunRef;
@@ -139,6 +179,8 @@ export interface RunLease {
     readonly record: RunRecord;
     /** The seal the previous incarnation's clean release wrote; null on a first run and after a crash. */
     readonly sealedSeq: number | null;
+    /** `run.json` as the open found it, before it wrote this incarnation's: null when there was none (a new run's first open). */
+    readonly previous: RunRecord | null;
     readonly fenced: boolean;
     /**
      * The seal check on the app's store, before anything commits: the store's head (`storeHead`) below
@@ -228,12 +270,12 @@ export interface StoreHeadSource {
     readonly file: string;
 }
 /**
- * The last sequence the store committed: the one read of pi's internal schema in this package. pi-durable 1.0.4's
- * public `Storage` has no head query, and the seal check must run before `Harness.open` can commit (its recovery commit
- * would reuse a lost sequence number). pi's SqliteStorage gives each commit `durable_metadata.next_seq` and stores the
- * successor in the same transaction, so the head is `next_seq - 1`. The query only reads. A store without that table,
- * row or column fails closed (STORE_HEAD_UNREADABLE), so a pi whose schema moved never skips the check silently;
- * a unit test pins the read to the sequence pi's commits return.
+ * The last sequence the store committed: the one read of pi's internal schema in this package. pi-durable's public
+ * `Storage` has no head query (1.0.4 and 1.1.0), and the seal check must run before `Harness.open` can commit (its
+ * recovery commit would reuse a lost sequence number). pi's SqliteStorage gives each commit `durable_metadata.next_seq`
+ * and stores the successor in the same transaction, so the head is `next_seq - 1`. The query only reads. A store
+ * without that table, row or column fails closed (STORE_HEAD_UNREADABLE), so a pi whose schema moved never skips the
+ * check silently; a unit test pins the read to the sequence pi's commits return.
  *
  * `database` is the store's fence-aware facade (`FencedDatabase`), which turns an I/O-class error into a fence; through
  * a raw connection such an error would read as STORE_HEAD_UNREADABLE.

package/dist/run.js

@@ -10,6 +10,7 @@ import { DatabaseSync } from "node:sqlite";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { Harness } from "@earendil-works/pi-durable";
 import { acquire } from "./claim.js";
+import { reapOrRefuse } from "./commands.js";
 import { archilEnv } from "./env.js";
 import { EXIT_FENCED, FencedError, HeldError, ownWriteFenced, PdaError } from "./errors.js";
 import { openArchilStore } from "./store.js";
@@ -59,6 +60,18 @@ export class LeaseLapsedError extends FencedError {
         this.by = by;
     }
 }
+/**
+ * `storage`'s four reads on a frozen object that holds nothing else: no `commit` or `mintId` on it, and no reference to
+ * `storage` a cast could reach.
+ */
+function storeReads(storage) {
+    return Object.freeze({
+        scanConversations: (...args) => storage.scanConversations(...args),
+        scanTasks: (...args) => storage.scanTasks(...args),
+        scanDocuments: (...args) => storage.scanDocuments(...args),
+        document: (...args) => storage.document(...args),
+    });
+}
 /** Locks this process holds. A collected DatabaseSync closes its file, which would drop the lock without a word. */
 const heldLocks = new Set();
 const SQLITE_BUSY = 5;
@@ -119,12 +132,12 @@ export function takeOwnerLock(root) {
     };
 }
 /**
- * The last sequence the store committed: the one read of pi's internal schema in this package. pi-durable 1.0.4's
- * public `Storage` has no head query, and the seal check must run before `Harness.open` can commit (its recovery commit
- * would reuse a lost sequence number). pi's SqliteStorage gives each commit `durable_metadata.next_seq` and stores the
- * successor in the same transaction, so the head is `next_seq - 1`. The query only reads. A store without that table,
- * row or column fails closed (STORE_HEAD_UNREADABLE), so a pi whose schema moved never skips the check silently;
- * a unit test pins the read to the sequence pi's commits return.
+ * The last sequence the store committed: the one read of pi's internal schema in this package. pi-durable's public
+ * `Storage` has no head query (1.0.4 and 1.1.0), and the seal check must run before `Harness.open` can commit (its
+ * recovery commit would reuse a lost sequence number). pi's SqliteStorage gives each commit `durable_metadata.next_seq`
+ * and stores the successor in the same transaction, so the head is `next_seq - 1`. The query only reads. A store
+ * without that table, row or column fails closed (STORE_HEAD_UNREADABLE), so a pi whose schema moved never skips the
+ * check silently; a unit test pins the read to the sequence pi's commits return.
  *
  * `database` is the store's fence-aware facade (`FencedDatabase`), which turns an I/O-class error into a fence; through
  * a raw connection such an error would read as STORE_HEAD_UNREADABLE.
@@ -265,6 +278,9 @@ class Lease {
     get sealedSeq() {
         return this.#previous?.sealedSeq ?? null;
     }
+    get previous() {
+        return this.#previous ?? null;
+    }
     get fenced() {
         return this.#fence !== undefined;
     }
@@ -605,9 +621,12 @@ async function openLease(ref, options, step) {
     catch (error) {
         throw new RunError("INVALID_ARGUMENT", `holder ${JSON.stringify(options.holder)}: ${error.message}`, { cause: error });
     }
+    if (options.acquire === undefined && !options.mountToken) {
+        throw new RunError("INVALID_ARGUMENT", "mountToken is required to mount an Archil disk; a run on a local directory passes localRun(root) instead");
+    }
     const claim = await step("acquire", () => (options.acquire ?? acquire)({
         ref,
-        token: options.mountToken,
+        token: options.mountToken ?? "",
         ...(options.mountRoot === undefined ? {} : { mountRoot: options.mountRoot }),
         ...(options.force === undefined ? {} : { force: options.force }),
         ...(options.host === undefined ? {} : { host: options.host }),
@@ -680,6 +699,15 @@ class Run {
         const storage = lease.observe(this.#store.storage);
         this.#harness = await step("harness", () => Harness.open(storage, { ...this.#options.harness, env: this.env }, this.#context));
         await step("live", () => lease.live());
+        const before = this.#options.beforeResume;
+        if (before) {
+            // The storage the Harness was opened over (the lease observes its commits), and its head now: nothing commits
+            // between the open and the hook, since the Harness has not resumed.
+            await step("before-resume", async () => {
+                const head = (await storeHead(this.#store));
+                await before({ harness: this.#harness, context: this.#context, generation: lease.generation, record: lease.record, previous: lease.previous, claim: lease.claim, storage: storeReads(storage), head });
+            });
+        }
         await step("resume", () => this.#harness.resume());
     }
     /** Undo a failed open: close what this layer opened, then the lease's own undo. */
@@ -735,6 +763,13 @@ export async function openDurableRun(ref, options) {
     let env;
     const lease = await openLease(ref, { ...options, context, cleanup: (c) => env?.cleanup(c) ?? Promise.resolve() }, step);
     try {
+        // A claim that records its commands (a local run's): end what a killed incarnation left running, now that the owner
+        // lock is held and before the Harness opens, so no command of it still writes in work/ once the run resumes.
+        const commands = lease.rawClaim.commands;
+        // A process of a killed incarnation that outlives its SIGKILL refuses the open (HeldError, 76): the run never resumes
+        // beside it, and its record stays for the next open.
+        if (commands !== undefined)
+            await step("commands", () => reapOrRefuse(commands));
         env = (options.env ?? ((c) => archilEnv(c)))(lease.rawClaim);
     }
     catch (error) {

package/dist/status.d.ts

@@ -19,7 +19,7 @@ export type RunStatus = (typeof RUN_STATUSES)[number];
 export interface RunHolder {
     readonly driver: string;
     readonly host: string;
-    /** `/proc/sys/kernel/random/boot_id`; null where the platform has none. */
+    /** `/proc/sys/kernel/random/boot_id` (`kern.bootsessionuuid` on macOS); null where it cannot be read. */
     readonly bootId: string | null;
     readonly pid: number;
     /** When this incarnation claimed the run (ISO 8601). */
@@ -81,12 +81,14 @@ export declare const ARCHIL_FSTYPE = "fuse.archil";
  * A run root held open as a directory for the life of the instance. `at` is `/proc/self/fd/<n>`, a path the kernel
  * resolves through the open directory and never through the root's path (Node has no openat; the magic link stands in
  * for it): a file made, written or renamed under `at` is in the directory opened at acquire, or the call fails (ENOTCONN
- * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away.
+ * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away. macOS has no
+ * such link: there `at` is the root's path (`byPath`), and only the checks below stand between a write and a root that was
+ * replaced.
  */
 export interface ClaimDir {
     /** The root's path, as the claim names it. */
     readonly root: string;
-    /** `/proc/self/fd/<n>`. Throws once closed: the number may then name another file. */
+    /** `/proc/self/fd/<n>`, or the root's path `byPath`. Throws once closed: the number may then name another file. */
     readonly at: string;
     /**
      * Resolves while the root's path still resolves to the directory held open (same device, same inode). A mount that was
@@ -107,6 +109,12 @@ export interface OpenClaimDirOptions {
     readonly fstype?: string | null;
     /** Default `/proc/self/mountinfo`. */
     readonly mountinfo?: string;
+    /**
+     * `at` is the root's path, not `/proc/self/fd/<n>`: the default on macOS, which has none. A write is checked against the
+     * held directory first (`assertMounted`), but a root renamed and replaced between that check and the write gets the
+     * write. For a local directory only.
+     */
+    readonly byPath?: boolean;
 }
 /** `major:minor` of a device number, as `/proc/self/mountinfo` writes it (glibc's encoding). */
 export declare function deviceName(dev: bigint): string;

package/dist/status.js

@@ -2,11 +2,12 @@
 // claim with write-to-temp, fsync, rename, and read by the supervisor (over the S3 API or a local mount). It is a hint
 // for the supervisor, never the source of truth: the store is. Any error writing it is a fence. The instance writes it
 // through its claim directory (`ClaimDir`), never by path, so a write cannot land under a mountpoint whose mount is gone.
-import { constants, readFileSync } from "node:fs";
+import { constants } from "node:fs";
 import { open, readFile, rename, rm, stat } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+import { thisBoot } from "./process-table.js";
 export const RUN_JSON = "run.json";
 /** The temporary file every write goes through; renamed over `run.json` once it is fsynced. */
 export const RUN_JSON_TEMP = "run.json.tmp";
@@ -204,7 +205,8 @@ export async function openClaimDir(root, options = {}) {
         await handle.close().catch(() => undefined);
         throw error instanceof FencedError ? error : unmounted(`checking the claim root ${root} failed: ${error.message}`, error);
     }
-    const at = `/proc/self/fd/${handle.fd}`;
+    const byPath = options.byPath ?? process.platform === "darwin";
+    const at = byPath ? root : `/proc/self/fd/${handle.fd}`;
     let closed = false;
     const same = (path, now, claims) => {
         if (now.dev === claims.dev && now.ino === claims.ino)
@@ -234,10 +236,18 @@ export async function openClaimDir(root, options = {}) {
         async assertSame(name) {
             if (closed)
                 throw unmounted(`the claim directory of ${root} is closed`);
-            const [byPath, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
+            if (byPath) {
+                // No second way to name the entry: the root must still be the directory held, and the entry on its device.
+                const [dir, entry] = await Promise.all([statOf(root), statOf(join(root, name))]);
+                same(root, dir, held);
+                if (entry.dev !== held.dev)
+                    throw unmounted(`${name} in the claim directory is on device ${deviceName(entry.dev)}, not the claim's ${deviceName(held.dev)}`);
+                return;
+            }
+            const [named, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
             if (inDir.dev !== held.dev)
                 throw unmounted(`${name} in the claim directory is on device ${deviceName(inDir.dev)}, not the claim's ${deviceName(held.dev)}`);
-            same(join(root, name), byPath, inDir);
+            same(join(root, name), named, inDir);
         },
         async close() {
             if (closed)
@@ -247,18 +257,10 @@ export async function openClaimDir(root, options = {}) {
         },
     };
 }
-function bootId() {
-    try {
-        return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * This process as a holder: the host driver's `handle` (default driver `local`, this machine's host name and boot id)
  * with this process's pid and `since`. A handle whose named fields have the wrong type is refused (RunRecordError).
  */
 export function currentHolder(handle = {}, since = new Date()) {
-    return holderOf({ driver: "local", host: hostname(), bootId: bootId(), ...handle, pid: process.pid, since: since.toISOString() });
+    return holderOf({ driver: "local", host: hostname(), bootId: thisBoot(), ...handle, pid: process.pid, since: since.toISOString() });
 }

package/dist/store.d.ts

@@ -39,8 +39,18 @@ export declare const PROFILE_PRAGMAS: {
         readonly mmap_size: 0;
     };
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export declare function assertPragmas(database: SqliteExecutor, profile: Profile): Promise<void>;
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export declare const FULLFSYNC_PRAGMAS: {
+    readonly fullfsync: 1;
+    readonly checkpoint_fullfsync: 1;
+};
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export declare function profilePragmas(profile: Profile, platform?: NodeJS.Platform): Readonly<Record<string, string | number>>;
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export declare function assertPragmas(database: SqliteExecutor, profile: Profile, platform?: NodeJS.Platform): Promise<void>;
 /**
  * The fenced state of one handle. The first error whose result code is in the I/O, full or not-a-database class marks it
  * fenced, runs `onFenced` once (before the error propagates), and from then on every operation fails with the same
@@ -84,6 +94,8 @@ export type OpenOptions = {
     readonly onFenced?: (error: StoreFencedError) => void;
     /** Wraps the raw database inside the fence, for instrumentation and fault injection. */
     readonly decorate?: (database: SqliteDatabase) => SqliteDatabase;
+    /** The platform whose pragmas the store takes (`profilePragmas`); default this one. For tests. */
+    readonly platform?: NodeJS.Platform;
 };
 export type ArchilStore = {
     readonly storage: SqliteStorage;

package/dist/store.js

@@ -64,10 +64,19 @@ export const PROFILE_PRAGMAS = {
     exclusive: { locking_mode: "exclusive", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
     shared: { locking_mode: "normal", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export async function assertPragmas(database, profile) {
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export const FULLFSYNC_PRAGMAS = { fullfsync: 1, checkpoint_fullfsync: 1 };
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export function profilePragmas(profile, platform = process.platform) {
+    return platform === "darwin" ? { ...PROFILE_PRAGMAS[profile], ...FULLFSYNC_PRAGMAS } : PROFILE_PRAGMAS[profile];
+}
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export async function assertPragmas(database, profile, platform = process.platform) {
     const mismatches = [];
-    for (const [pragma, expected] of Object.entries(PROFILE_PRAGMAS[profile])) {
+    for (const [pragma, expected] of Object.entries(profilePragmas(profile, platform))) {
         const row = await database.get(`PRAGMA ${pragma}`);
         const actual = row === undefined ? undefined : Object.values(row)[0];
         if (actual !== expected)
@@ -203,7 +212,10 @@ export async function openArchilStore(file, profile = "exclusive", options = {})
         }
         await database.exec("PRAGMA synchronous = FULL"); // fsync the WAL on every commit
         await database.exec("PRAGMA mmap_size = 0"); // no mmap I/O of the database file on a network filesystem
-        await assertPragmas(database, profile);
+        const platform = options.platform ?? process.platform;
+        for (const pragma of platform === "darwin" ? Object.keys(FULLFSYNC_PRAGMAS) : [])
+            await database.exec(`PRAGMA ${pragma} = ON`);
+        await assertPragmas(database, profile, platform);
         const storage = await SqliteStorage.open(database);
         return { storage, database, profile, file };
     }

package/dist/supervise.d.ts

@@ -241,6 +241,25 @@ export type TokenUser = {
     expiresAt?: string;
     createdAt?: string;
 };
+/** What `archilControl` returns: everything `ensureRunning`, `superviseRuns`, `checkHost`, `fork` and the token janitor use. */
+export type ArchilControl = SupervisorControl & CheckControl & {
+    listUsers(): Promise<TokenUser[]>;
+};
+/** The two calls of the `disk` client (this package's dependency) that `archilControl` makes. */
+export type DiskClient = Pick<typeof import("disk"), "configure" | "getDisk">;
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export declare function archilControl(options: {
+    readonly apiKey: string;
+    readonly disk: string;
+    readonly region: string;
+    readonly client?: DiskClient;
+}): Promise<ArchilControl>;
 export interface TokenSweepOptions {
     /** The disk's token users (`getDisk(id).authorizedUsers`; the list lags by seconds). */
     listUsers(): Promise<TokenUser[]>;
@@ -330,9 +349,9 @@ export declare function checkHost(options: CheckOptions): Promise<CheckReport>;
 /**
  * Delete a run's directory tree over S3. A tree with a delegation on it, even an orphaned one, is not deleted: S3
  * DeleteObjects leaves its objects in place and reports no error, and the run id would later reopen with its old
- * store. So: revoke every delegation on the subtree, delete the files, then the directory markers deepest first (a
- * directory with children refuses), then list the prefix. Anything left is RUN_TREE_NOT_DELETED; a non-empty prefix is
- * never reported as deleted.
+ * store. So: revoke every delegation on the subtree and its holders' private directories, delete the files, then the
+ * directory markers deepest first (a directory with children refuses), then list the prefix. Anything left is
+ * RUN_TREE_NOT_DELETED; a non-empty prefix is never reported as deleted.
  */
 export declare function deleteRunTree(control: CheckControl, id: string): Promise<{
     objects: number;

package/dist/supervise.js

@@ -6,7 +6,7 @@
 import { open } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join } from "node:path";
-import { acquire, createRunDir, findDelegations, matchDelegations, pathlessResolver, mintMountToken, MOUNT_TOKEN_TTL, parseTokenNickname, removeMountToken, runPath, unmountClaim, } from "./claim.js";
+import { acquire, createRunDir, findDelegations, matchDelegations, pathlessResolver, revokeBestEffort, revokeCompanions, mintMountToken, MOUNT_TOKEN_TTL, parseTokenNickname, removeMountToken, runPath, unmountClaim, } from "./claim.js";
 import { FencedError, HeldError, PdaError } from "./errors.js";
 import { parseRunRecord, RUN_JSON } from "./status.js";
 export const CONTROL_TIMEOUT_MS = 10_000;
@@ -106,7 +106,7 @@ export async function ensureRunning(ref, host, options) {
     }
     // A due wake still goes through the delegation check: an instance that wrote `sleeping` and died before releasing
     // left a held or orphaned delegation, which a plain start would hit (76) on every tick.
-    const held = await listHeld(opts.control, ref.id, opts.pathless);
+    const { held, all } = await listHeld(opts.control, ref.id, opts.pathless);
     // A start in flight: the instance has not written run.json at its generation yet (it may not even have mounted).
     // Revoking it or starting a second one would fence what was just started.
     const baseGraceMs = opts.startGraceMs ?? leaseExpiryMs;
@@ -144,7 +144,7 @@ export async function ensureRunning(ref, host, options) {
         const inFlight = await starting();
         if (inFlight)
             return inFlight;
-        await revokeListed(opts.control, ref.id, held);
+        await revokeListed(opts.control, ref.id, held, all);
         return start("orphaned", held);
     }
     if (held.some((d) => d.isPending && !d.isOrphaned))
@@ -157,7 +157,7 @@ export async function ensureRunning(ref, host, options) {
     if (inFlight)
         return inFlight;
     const stonith = status?.holder ? await stopHolder(host, status.holder, opts.stonithTimeoutMs ?? STONITH_TIMEOUT_MS) : { outcome: "no-holder" };
-    await revokeListed(opts.control, ref.id, held);
+    await revokeListed(opts.control, ref.id, held, all);
     return start("lease-expired", held, stonith);
 }
 /**
@@ -219,9 +219,11 @@ async function ensureRunDir(control, id, owner) {
     await createRunDir(control, id, owner);
     return true;
 }
+/** The run's delegations (`matchDelegations`), and the listing they came from. */
 async function listHeld(control, id, resolve) {
     try {
-        return await findDelegations(control, id, resolve);
+        const all = await control.listDelegations();
+        return { held: await matchDelegations(all, id, resolve ?? pathlessResolver(control)), all };
     }
     catch (err) {
         throw new SuperviseError("CONTROL_API_FAILED", `listing delegations on ${runPath(id)} failed`, { cause: err });
@@ -231,18 +233,20 @@ const sameDelegation = (a, b) => a.clientId === b.clientId && a.inodeId === b.in
 /**
  * Revoke exactly the delegations the decision was made on, never a fresh listing: a racing supervisor may have started
  * a new holder since, and that one is not ours to judge. A revoke that fails is fine only if the delegation is gone.
+ * Then the same clients' private directories (`revokeCompanions`): those clients are gone or fenced.
  */
-async function revokeListed(control, id, held) {
+async function revokeListed(control, id, held, all) {
     for (const d of held) {
         try {
             await control.revokeDelegation({ clientId: d.clientId, inodeId: d.inodeId });
         }
         catch (err) {
-            const still = await listHeld(control, id).then((now) => now.some((n) => sameDelegation(n, d)));
+            const still = await listHeld(control, id).then((now) => now.held.some((n) => sameDelegation(n, d)));
             if (still)
                 throw new SuperviseError("CONTROL_API_FAILED", `revoking ${runPath(id)} (client ${d.clientId}) failed`, { cause: err });
         }
     }
+    await revokeCompanions(control, held, all);
 }
 function settleWithin(promise, ms) {
     return new Promise((resolve) => {
@@ -343,6 +347,31 @@ export async function superviseRuns(refs, host, opts) {
     }
     return out;
 }
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export async function archilControl(options) {
+    const { configure, getDisk } = options.client ?? (await import("disk"));
+    configure({ apiKey: options.apiKey, region: options.region });
+    const disk = await getDisk(options.disk);
+    return {
+        getObject: (key) => disk.getObject(key),
+        headObject: (key) => disk.headObject(key),
+        putObject: (key, body, putOptions) => disk.putObject(key, body, putOptions),
+        addUser: (user) => disk.addUser(user),
+        removeUser: (type, identifier) => disk.removeUser(type, identifier),
+        listDelegations: () => disk.listDelegations(),
+        revokeDelegation: (d) => disk.revokeDelegation(d),
+        exec: (command) => disk.exec(command),
+        listObjects: (prefix, listOptions) => disk.listObjects(prefix, listOptions),
+        deleteObjects: (keys, deleteOptions) => disk.deleteObjects(keys, deleteOptions),
+        listUsers: async () => (await getDisk(options.disk)).authorizedUsers ?? [],
+    };
+}
 const RELEASED = ["paused", "sleeping", "done", "failed"];
 /**
  * Remove mount-token users that no live mount needs. Removing a token user under a live mount makes that mount lose its
@@ -501,15 +530,13 @@ export async function checkHost(options) {
 /**
  * Delete a run's directory tree over S3. A tree with a delegation on it, even an orphaned one, is not deleted: S3
  * DeleteObjects leaves its objects in place and reports no error, and the run id would later reopen with its old
- * store. So: revoke every delegation on the subtree, delete the files, then the directory markers deepest first (a
- * directory with children refuses), then list the prefix. Anything left is RUN_TREE_NOT_DELETED; a non-empty prefix is
- * never reported as deleted.
+ * store. So: revoke every delegation on the subtree and its holders' private directories, delete the files, then the
+ * directory markers deepest first (a directory with children refuses), then list the prefix. Anything left is
+ * RUN_TREE_NOT_DELETED; a non-empty prefix is never reported as deleted.
  */
 export async function deleteRunTree(control, id) {
     const prefix = `${runPath(id)}/`;
-    const held = await findDelegations(control, id);
-    for (const d of held)
-        await control.revokeDelegation({ clientId: d.clientId, inodeId: d.inodeId }).catch(() => { });
+    const held = await revokeBestEffort(control, id);
     const keys = (await control.listObjects(prefix, { recursive: true })).objects.map((o) => o.key);
     const dirs = [...new Set([...keys.filter((k) => k.endsWith("/")), prefix])];
     const depth = (k) => k.split("/").length;

package/dist/watchdog.d.ts

@@ -9,6 +9,8 @@ export interface SweepOptions {
     readonly proc?: string;
     readonly sys?: string;
     readonly kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Lists processes with this ps(1) instead of reading `proc`: the default on macOS, which has no /proc, unless `proc` is given. */
+    readonly ps?: (file: string, args: readonly string[]) => string;
 }
 /** One look at the shared state at `now`. True once the lease has lapsed, for good; the first look records the age. */
 export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
@@ -16,7 +18,7 @@ export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
  * SIGKILL the instance's commands: the process group of each direct child (pi starts each command as its own group's
  * leader), or the child alone when it shares the instance's group; with `ownCgroup`, every other process of the cgroup.
  * Never the instance or its group. A process this user may not signal (sudo's archil helpers) is skipped. Returns the
- * number of signals sent. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
  * spaces and parentheses.
  */
 export declare const sweep: (instance: number, options?: SweepOptions) => number;