@parcha/pi-durable-disk 0.1.0-beta.16 → 0.1.0-beta.18

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.1.0-beta.17 (2026-10-18)
+
+- **A claim directory's descriptor is closed by `close()` only, never by garbage collection (GRE-3853)**
+  - While a new run's seed waited on a promise nothing else held, the open's pending await chain was all that reached the
+    claim directory, so a collection could close its FileHandle. The start mark's keeper, which writes through
+    `/proc/self/fd/<n>` on a thread of its own, then failed silently, and the supervisor's grace ran out under a live seed.
+    A later open in the process could also be handed that number, and the keeper would have written the mark there.
+  - Every handle the package hands out as `/proc/self/fd/<n>` (the claim directory's `at`, a confined pin's paths, the walk
+    that makes them, the text line reader and the temp directory) is now held until it is closed.
+  - The keeper writes only while its directory is still the one it started on (same device and inode). If the directory
+    can't be reached or is another one, it stops. Its first failure is a process warning, code `PDA_START_MARK`, not
+    silence.
+
 ## 0.1.0-beta.16 (2026-10-18)
 
 - **A place's outcome carries the models the run's live parts chose (`PlaceOutcome.models`)**

package/README.md

@@ -767,7 +767,8 @@ await openDurableRun(ref, {
   (`--start-grace`, `startGraceMs`; default the lease expiry, 90 s) only while its start mark (`start.json`) is younger
   than the grace. So while the seed runs, the instance rewrites the mark's time every heartbeat, through its claim, when a
   supervisor's mark for generation 1 is there. It does so on a thread of its own, so a seed that holds its thread (a
-  synchronous import through `DatabaseSync`) is covered too. A live seed of any length stays `starting`. A seeder that dies stops
+  synchronous import through `DatabaseSync`) is covered too. A live seed of any length stays `starting`. If the mark
+  can't be rewritten, the instance says so once, as a process warning with code `PDA_START_MARK`. A seeder that dies stops
   rewriting, the grace runs out as for any start, and the claim is revoked. If the claim is revoked while the seed still
   runs, its next write or its barrier is refused, the instance is fenced (exit 75) with nothing published, and the next
   start seeds again.

package/dist/confine.js

@@ -20,6 +20,7 @@ import { constants, existsSync, realpathSync } from "node:fs";
 import { lstat, mkdir, open, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { err, FileError, ok } from "@earendil-works/pi-durable/env";
+import { fdPath, hold } from "./held-fd.js";
 /**
  * A file operation named a path that is not under the workspace (`outside_work`), or one whose components changed
  * while it was being resolved (`changed`). pi turns it into a failed tool result that names the path. Its `code` is pi's
@@ -153,7 +154,7 @@ export class Pin {
         this.name = name;
         this.#byPath = held.byPath;
         this.#names = held.names ?? [];
-        this.dir = held.byPath ? held.path : `/proc/self/fd/${handle.fd}`;
+        this.dir = held.byPath ? (hold(handle), held.path) : fdPath(handle);
         this.entry = dirMode ? this.dir : name === "" ? `${this.dir}/.` : `${this.dir}/${name}`;
         this.#real = dirMode || name === "" ? canonical : dirname(canonical);
     }
@@ -354,14 +355,14 @@ async function walk(root, names, create, canonical, byPath = false) {
     }
     try {
         // The root was opened by name: it must be the directory that name denotes now, not one swapped in on the way.
-        const actual = await readlink(`/proc/self/fd/${dir.fd}`);
+        const actual = await readlink(fdPath(dir));
         if (actual !== root)
             throw changed(canonical);
         let real = root;
         for (const name of names) {
             if (name === "" || name === "." || name === ".." || name.includes("\0"))
                 throw changed(canonical);
-            const step = `/proc/self/fd/${dir.fd}/${name}`;
+            const step = `${fdPath(dir)}/${name}`;
             real = join(real, name);
             let next;
             try {

package/dist/env.js

@@ -14,6 +14,7 @@ import { CodingTools } from "@earendil-works/pi-durable/tools";
 import { COMMANDS_MARK, CommandRecorder } from "./commands.js";
 import { canonicalizeSync, confineHooks, Confinement, fileError, inside, namesHeld, PathOutsideWorkError } from "./confine.js";
 import { PdaError } from "./errors.js";
+import { fdPath } from "./held-fd.js";
 /**
  * What `exec` returns once the factory's `cleanup()` ran: no command was started. Its `code` is pi's `spawn_error`
  * (the command could not start), `reason` tells it apart from a program that failed to spawn.
@@ -153,7 +154,7 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
         // pi opens the file again through the handle's own `/proc/self/fd` entry, which names that inode and no path; by path
         // (macOS), through the path just checked.
         const byPath = this.#scope.confinement.byPath;
-        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle, pin) => super.openTextLineReader(byPath ? pin.entry : `/proc/self/fd/${handle.fd}`, context));
+        return this.#file(path, context, { access: "read", flags: constants.O_RDONLY }, (handle, pin) => super.openTextLineReader(byPath ? pin.entry : fdPath(handle), context));
     }
     async openBinaryReader(path, options, context) {
         if (this.#scope.confinement === undefined)
@@ -314,7 +315,7 @@ class ArchilExecutionEnv extends NodeExecutionEnv {
                 // By path (macOS): made under tmp/'s path once that path is checked to still name the directory held.
                 if (confinement.byPath && !(await namesHeld(tempRoot, held)))
                     throw new PathOutsideWorkError(tempRoot, "changed", `${tempRoot}: changed while it was being resolved`);
-                name = basename(await mkdtemp(`${confinement.byPath ? tempRoot : `/proc/self/fd/${held.fd}`}/${prefix ?? "tmp-"}`));
+                name = basename(await mkdtemp(`${confinement.byPath ? tempRoot : fdPath(held)}/${prefix ?? "tmp-"}`));
             }
             finally {
                 await held.close();

package/dist/held-fd.d.ts

@@ -0,0 +1,5 @@
+import type { FileHandle } from "node:fs/promises";
+/** Keeps `handle` reachable until it is closed. A handle held and never closed stays open until the process exits. */
+export declare function hold(handle: FileHandle): FileHandle;
+/** `/proc/self/fd/<n>` for `handle`, held until it is closed (`hold`). */
+export declare function fdPath(handle: FileHandle): string;

package/dist/held-fd.js

@@ -0,0 +1,14 @@
+const HELD = new Set();
+/** Keeps `handle` reachable until it is closed. A handle held and never closed stays open until the process exits. */
+export function hold(handle) {
+    if (!HELD.has(handle)) {
+        HELD.add(handle);
+        // A FileHandle is an EventEmitter that emits `close` once closed (Node's typings leave that out).
+        handle.once("close", () => HELD.delete(handle));
+    }
+    return handle;
+}
+/** `/proc/self/fd/<n>` for `handle`, held until it is closed (`hold`). */
+export function fdPath(handle) {
+    return `/proc/self/fd/${hold(handle).fd}`;
+}

package/dist/place.js

@@ -2,7 +2,7 @@
 // kill (agentrun's reference demo) is the same for every place; the place decides how. `localPlace` runs the instance on
 // a directory of this machine (`run --dir`, no disk and no key); `archilPlace` runs it on an Archil disk through a host
 // driver, mints each attempt's mount token itself and takes the run over after a kill. The types match the reference's
-// place seam (examples/reference/place.ts) structurally. The supervisor reads nothing under the run's directory: the
+// place seam (@parcha/agentrun-harness/place) structurally. The supervisor reads nothing under the run's directory: the
 // outcome, the run's record and its delegations come through the place.
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";

package/dist/run.js

@@ -361,7 +361,7 @@ class Lease {
                 // While a new run seeds it has no `run.json` heartbeat, and a supervisor keeps a start in its grace only while its
                 // start mark is younger than the grace: the mark is kept fresh until the seed ends, through the held claim directory.
                 // A seeder that dies stops, and the grace runs out as for any start.
-                const stop = keepStartMark(this.#dir.at, this.#lease.heartbeatMs);
+                const stop = keepStartMark(this.#dir.at, this.#lease.heartbeatMs, claim.root);
                 try {
                     await seed({ root: claim.root, storePath: join(claim.store, STORE_FILE), workDir: claim.work });
                 }

package/dist/status.d.ts

@@ -98,10 +98,12 @@ export declare function parseStartMark(text: string): StartMark | null;
 /**
  * Keeps a supervisor's start mark for generation 1 in `dir` fresh: its `at` rewritten every `everyMs` (temp file, fsync,
  * rename, fsync the directory), the rest of it as the supervisor wrote it; nothing is made when there is none. On a thread of
- * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Best effort: a refused write leaves
- * the mark as it was. Returns the stop, which resolves once the thread has exited, so no write outlives it.
+ * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Only while `dir` is the directory
+ * the keeper first saw there. Best effort: a failure leaves the mark as it was, and the first one is a process warning
+ * (`PDA_START_MARK`) naming `label`; the grace then runs out as for any start. Returns the stop, which resolves once the
+ * thread has exited, so no write outlives it.
  */
-export declare function keepStartMark(dir: string, everyMs: number): () => Promise<void>;
+export declare function keepStartMark(dir: string, everyMs: number, label?: string): () => Promise<void>;
 /** The FencedError code of a claim root that is no longer the mount the instance opened (unmounted, lazily or not). */
 export declare const CLAIM_UNMOUNTED = "CLAIM_UNMOUNTED";
 /** The file system type of an Archil mount in the mount table. */

package/dist/status.js

@@ -8,6 +8,7 @@ import { hostname } from "node:os";
 import { join } from "node:path";
 import { Worker } from "node:worker_threads";
 import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+import { fdPath, hold } from "./held-fd.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. */
@@ -181,17 +182,53 @@ export function parseStartMark(text) {
 }
 // The keeper's code is plain CommonJS in a string, started with `eval: true` and no inherited Node flags, as the lease
 // watchdog's is (src/watchdog.ts says why). One refresh at a time, all synchronous: a stop (the message) is handled only
-// between two refreshes, so none is still writing once the thread has exited.
+// between two refreshes, so none is still writing once the thread has exited. It writes only while `dir` is still the
+// directory it first saw (its device and inode, read on this thread, so a stalled mount never holds the caller's): a path
+// that names another (a descriptor number reused) or none is never written, and the keeper stops. Its first failure goes
+// to the main thread, once.
 const KEEPER_SOURCE = `"use strict";
 const fs = require("node:fs");
 const path = require("node:path");
 const { parentPort, workerData } = require("node:worker_threads");
 const { dir, name, everyMs } = workerData;
 const file = path.join(dir, name);
+let first;
+let stopped = false;
+let reported = false;
+const report = (message) => {
+  if (reported) return;
+  reported = true;
+  parentPort.postMessage(message);
+};
 function refresh() {
+  if (stopped) return;
+  let now;
+  try {
+    now = fs.statSync(dir, { bigint: true });
+  } catch (error) {
+    stopped = true;
+    return report("its directory cannot be reached (" + (error.code || error.message) + "), so it is no longer the directory the keeper started on");
+  }
+  first ??= { dev: now.dev, ino: now.ino };
+  if (now.dev !== first.dev || now.ino !== first.ino) {
+    stopped = true;
+    return report("its directory is no longer the directory the keeper started on");
+  }
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return; // no mark: nothing to keep
+    return report("reading it failed (" + (error.code || error.message) + ")");
+  }
+  let mark;
+  try {
+    mark = JSON.parse(text);
+  } catch {
+    return; // not a mark: nothing to keep
+  }
+  if (mark === null || typeof mark !== "object" || mark.generation !== 1 || typeof mark.at !== "string" || !Number.isFinite(Date.parse(mark.at))) return;
   try {
-    const mark = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (mark === null || typeof mark !== "object" || mark.generation !== 1 || typeof mark.at !== "string" || !Number.isFinite(Date.parse(mark.at))) return;
     const temp = file + ".tmp";
     const fd = fs.openSync(temp, "w", 0o644);
     try {
@@ -207,12 +244,12 @@ function refresh() {
     } finally {
       fs.closeSync(handle);
     }
-  } catch {
-    // absent, unreadable or refused
+  } catch (error) {
+    report("rewriting it failed (" + (error.code || error.message) + ")");
   }
 }
-refresh();
 const timer = setInterval(refresh, everyMs);
+refresh();
 parentPort.once("message", () => {
   clearInterval(timer);
   parentPort.close();
@@ -221,15 +258,17 @@ parentPort.once("message", () => {
 /**
  * Keeps a supervisor's start mark for generation 1 in `dir` fresh: its `at` rewritten every `everyMs` (temp file, fsync,
  * rename, fsync the directory), the rest of it as the supervisor wrote it; nothing is made when there is none. On a thread of
- * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Best effort: a refused write leaves
- * the mark as it was. Returns the stop, which resolves once the thread has exited, so no write outlives it.
+ * its own, so a caller whose thread is blocked (a synchronous import) is kept fresh too. Only while `dir` is the directory
+ * the keeper first saw there. Best effort: a failure leaves the mark as it was, and the first one is a process warning
+ * (`PDA_START_MARK`) naming `label`; the grace then runs out as for any start. Returns the stop, which resolves once the
+ * thread has exited, so no write outlives it.
  */
-export function keepStartMark(dir, everyMs) {
+export function keepStartMark(dir, everyMs, label = dir) {
+    const warn = (why) => process.emitWarning(`the start mark of ${label} is no longer kept fresh: ${why}; a supervisor's start grace runs out as for any start`, { code: "PDA_START_MARK" });
     const worker = new Worker(KEEPER_SOURCE, { eval: true, workerData: { dir, name: START_MARK, everyMs }, execArgv: [] });
+    worker.on("message", (why) => warn(why));
+    worker.on("error", (error) => warn(`its thread failed (${error.message})`));
     worker.unref();
-    worker.on("error", () => {
-        // the thread failed to start or threw: nothing more is refreshed, and the grace runs out as for any start
-    });
     const exited = new Promise((resolve) => worker.once("exit", () => resolve()));
     return () => {
         worker.ref();
@@ -295,7 +334,8 @@ export async function openClaimDir(root, options = {}) {
         throw error instanceof FencedError ? error : unmounted(`checking the claim root ${root} failed: ${error.message}`, error);
     }
     const byPath = options.byPath ?? process.platform === "darwin";
-    const at = byPath ? root : `/proc/self/fd/${handle.fd}`;
+    // Held until close(): `at` names the directory by its number, and a collection must never free that number.
+    const at = byPath ? (hold(handle), root) : fdPath(handle);
     let closed = false;
     const same = (path, now, claims) => {
         if (now.dev === claims.dev && now.ino === claims.ino)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.16",
+  "version": "0.1.0-beta.18",
   "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
   "keywords": [
     "pi",