@parcha/pi-durable-disk 0.1.0-beta.19 → 0.1.0-beta.21

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.1.0-beta.21 (2026-10-21)
+
+- `supervise --no-restart` is in the usage text and the reference: it turns off the local driver's restart on failure (`localHost({ restart: false })`), so an instance that exits stays down until the supervisor's next pass.
+
+## 0.1.0-beta.20 (2026-10-20)
+
+- A start mark keeper whose rewrite fails because the run's directory moved after its check now warns that the directory is no longer the one it started on, and stops. Before, the `PDA_START_MARK` warning said the rewrite failed (ENOENT or ENOTDIR). Nothing is written in either case; only the stated reason changes.
+- The local-disk env conformance cases watch with a 100 ms poll, so pi's fixed 3 s wait for a report keeps seconds of slack on a loaded runner; the product's 1 s watch default is unchanged.
+
 ## 0.1.0-beta.19 (2026-10-20)
 
 - An instance whose app released the run ends by itself: `pi-durable-disk run --app` exits 0 once `onOpen` has returned and the run is released, so the unit does not stay up with no mount.

package/dist/claim.d.ts

@@ -234,6 +234,11 @@ export declare function writtenSince(dir: string, since: number, limit?: number)
     fresh: string[];
     unchecked: string | null;
 }>;
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export declare const NO_TOKEN = "none";
 /**
  * Take the run's claim: mount `<disk>:/runs/<id>` exclusively at `<mountRoot>/runs/<id>` and verify it. A live mount of
  * the same run already there is kept (in-place restart); a dead one is cleaned first. With no mount there, a stale archil
@@ -242,11 +247,6 @@ export declare function writtenSince(dir: string, since: number, limit?: number)
  * verifying write is refused, MOUNTPOINT_NOT_EMPTY when the mountpoint cannot be emptied or archil still finds it not
  * empty, MOUNT_FAILED (exit 1) for a daemon of this host that is still running there.
  */
-/**
- * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
- * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
- */
-export declare const NO_TOKEN = "none";
 export declare function acquire(opts: AcquireOptions): Promise<Claim>;
 /** One exclusive mount of a path, as `withClaim` holds it: its own mountpoint, never reused. */
 export interface ExclusiveMount {

package/dist/claim.js

@@ -7,7 +7,7 @@ import { lstat, mkdir, open, readdir, readFile, rmdir, stat } from "node:fs/prom
 import { basename, isAbsolute, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { ClaimError, FencedError, HeldError, ownWriteFenced } from "./errors.js";
+import { ClaimError, EXIT_DATAERR, FencedError, HeldError, ownWriteFenced } from "./errors.js";
 export const DEFAULT_MOUNT_ROOT = "/mnt/archil";
 /** This package's `bin/archil-scoped`. A deployment installs a root-owned copy and passes its path as `archil`. */
 export const ARCHIL_SCOPED = fileURLToPath(new URL("../bin/archil-scoped", import.meta.url));
@@ -620,7 +620,7 @@ export async function writtenSince(dir, since, limit = STRAY_CHECK_LIMIT) {
     return { fresh, unchecked: null };
 }
 /** The exit of a start refused for the app's own writes before its claim (EX_DATAERR): a restart would write them again. */
-const EXIT_WRITTEN_BEFORE_MOUNT = 65;
+const EXIT_WRITTEN_BEFORE_MOUNT = EXIT_DATAERR;
 /** How many entries a directory holds; 0 when it cannot be read. */
 const entries = (dir) => readdir(dir).then((names) => names.length, () => 0);
 /**
@@ -701,6 +701,11 @@ async function verifyTarget(host, path, mountpoint, probe) {
         throw ownWriteFenced(join(mountpoint, CLAIM_PROBE), err);
     }
 }
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export const NO_TOKEN = "none";
 /**
  * Take the run's claim: mount `<disk>:/runs/<id>` exclusively at `<mountRoot>/runs/<id>` and verify it. A live mount of
  * the same run already there is kept (in-place restart); a dead one is cleaned first. With no mount there, a stale archil
@@ -709,11 +714,6 @@ async function verifyTarget(host, path, mountpoint, probe) {
  * verifying write is refused, MOUNTPOINT_NOT_EMPTY when the mountpoint cannot be emptied or archil still finds it not
  * empty, MOUNT_FAILED (exit 1) for a daemon of this host that is still running there.
  */
-/**
- * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
- * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
- */
-export const NO_TOKEN = "none";
 export async function acquire(opts) {
     const { ref, token } = opts;
     const path = runPath(ref.id);

package/dist/cli.d.ts

@@ -3,7 +3,6 @@ import { type Parking } from "./park.js";
 import { type RunServer } from "./serve.js";
 import { type ArchilControl, type DiskClient } from "./supervise.js";
 import { type DurableRun } from "./run.js";
-/** "30s", "500ms", "2m", "1h", or plain milliseconds. */
 /**
  * Whether the lease watchdog may kill every other process in the instance's cgroup: only inside its own systemd unit,
  * whose cgroup holds nothing but the instance and its commands. Elsewhere the cgroup may be shared (a login session, an
@@ -21,6 +20,7 @@ export declare function watchdogOwnsCgroup(holder: Record<string, unknown>, opti
     owns: boolean;
     warning?: string;
 };
+/** "30s", "500ms", "2m", "1h", or plain milliseconds. */
 export declare function parseDuration(text: string): number;
 /** `--run-as NAME|UID[:GID]`: the user the agent's commands run as, with its group and home from /etc/passwd when listed. */
 export declare function runUser(spec: string, passwd?: string): {

package/dist/cli.js

@@ -42,7 +42,7 @@ const USAGE = `usage:
                         [--user U] [--group G] [--app MODULE] [--run-arg ARG ...] [--lease-expiry 90s] [--stonith-timeout 30s]
                         [--start-grace 90s] [--start-backoff-max 10m] [--stop-timeout 30s] [--token-ttl 24h] [--token-prefix P] [--demand] [--create] [--env K=V ...] [--log-dir DIR]
                         [--archil BIN] [--control-timeout 10s] [--sweep-tokens] [--token-grace 15m]
-                        [--park-threshold 60s] [--api-key-env NAME]
+                        [--park-threshold 60s] [--no-restart] [--api-key-env NAME]
                         with --host docker: --image IMAGE [--app-root DIR] [--fleet F] [--name-prefix P] [--run-as USER]
                         [--docker-arg ARG ...] [--apparmor auto|PROFILE|none] [--docker BIN]
   pi-durable-disk supervise --check --disk D --region R [--mount-root DIR] [--user U] [--group G] [--check-id-prefix P]
@@ -51,7 +51,6 @@ const USAGE = `usage:
   pi-durable-disk release --id ID [--mount-root DIR]
   pi-durable-disk fork --disk D --region R --id ID --new-id NEW [--mount-root DIR] [--archil BIN] [--token-prefix P]
                         [--api-key-env NAME]`;
-/** "30s", "500ms", "2m", "1h", or plain milliseconds. */
 /**
  * Whether the lease watchdog may kill every other process in the instance's cgroup: only inside its own systemd unit,
  * whose cgroup holds nothing but the instance and its commands. Elsewhere the cgroup may be shared (a login session, an
@@ -90,6 +89,7 @@ export function watchdogOwnsCgroup(holder, options = {}) {
         return refuse(`the parent shares cgroup ${own}, so this process only inherited the handle`);
     return { owns: true };
 }
+/** "30s", "500ms", "2m", "1h", or plain milliseconds. */
 export function parseDuration(text) {
     const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(text.trim());
     if (!m)
@@ -219,7 +219,9 @@ async function runInstance(values) {
         throw new UsageError(`--serve-host ${serveHost} is not loopback: name a --serve-token-file`);
     const serveToken = tokenFile === undefined ? undefined : readServeToken(tokenFile);
     const mountRoot = str(values["mount-root"], DEFAULT_MOUNT_ROOT);
-    const root = dir ?? join(mountRoot, runPath(ref.id));
+    // On a disk the id names the run's directory: an unsafe one stops the instance here (INVALID_ARGUMENT), before it serves.
+    if (dir === undefined)
+        runPath(ref.id);
     const log = (event, extra = {}) => process.stderr.write(`${JSON.stringify({ at: new Date().toISOString(), event, run: ref.id, ...extra })}\n`);
     // The app's factory runs once the claim is held (`afterClaim`), so `ctx.root` is the live directory whenever app code
     // runs; what it returns opens the Harness. Serve starts before the open, with the root options the factory fills in.

package/dist/errors.d.ts

@@ -1,3 +1,7 @@
+/** EX_DATAERR: the run's data refuses to open (a store behind its seal, an unreadable `run.json`); a restart cannot help. */
+export declare const EXIT_DATAERR = 65;
+/** EX_SOFTWARE: this package cannot read the head of pi's store (pi's schema moved); a restart cannot help. */
+export declare const EXIT_SOFTWARE = 70;
 /** EX_TEMPFAIL: the claim was revoked or its mount failed; nothing this process writes can become durable. */
 export declare const EXIT_FENCED = 75;
 /**

package/dist/errors.js

@@ -2,6 +2,10 @@
 // another); both are terminal for the host's process supervisor, which must not restart into a run it lost.
 // A module's own errors extend FencedError or HeldError (overriding `code`) so one `instanceof` or `exitCodeFor` covers
 // them all, e.g. `class StoreFencedError extends FencedError` with `{ code: "STORE_FENCED" }`.
+/** EX_DATAERR: the run's data refuses to open (a store behind its seal, an unreadable `run.json`); a restart cannot help. */
+export const EXIT_DATAERR = 65;
+/** EX_SOFTWARE: this package cannot read the head of pi's store (pi's schema moved); a restart cannot help. */
+export const EXIT_SOFTWARE = 70;
 /** EX_TEMPFAIL: the claim was revoked or its mount failed; nothing this process writes can become durable. */
 export const EXIT_FENCED = 75;
 /**

package/dist/hosts/daytona.js

@@ -182,7 +182,6 @@ export function sandboxName(prefix, runId, now) {
     const stamp = `${now.toString(36)}${Math.floor(Math.random() * 1296).toString(36).padStart(2, "0")}`;
     return `${prefix}${slug}-${stamp}`.slice(0, 63);
 }
-/** The last line of a command's output that parses as JSON, or null. */
 /**
  * What the launcher printed, for a start it gave no reason for: the last 4 KB, or that it printed nothing. It prints only
  * its state; the mount token is in a root-only file it reads, never in its output.
@@ -191,6 +190,7 @@ function launcherOutput(text) {
     const out = text.trim();
     return out ? `the launcher printed: ${out.slice(-4096)}` : "the launcher printed nothing and exited 0";
 }
+/** The last line of a command's output that parses as JSON, or null. */
 function lastJson(text) {
     for (const line of text.trim().split("\n").reverse()) {
         try {

package/dist/hosts/local-host.js

@@ -17,7 +17,7 @@ import { hostname } from "node:os";
 import { extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ARCHIL_SCOPED, DEAD_CONNECTION, DEFAULT_MOUNT_ROOT, runPath } from "../claim.js";
-import { EXIT_FENCED, EXIT_HELD, PdaError } from "../errors.js";
+import { EXIT_DATAERR, EXIT_FENCED, EXIT_HELD, EXIT_SOFTWARE, PdaError } from "../errors.js";
 import { LOCAL_PARK_THRESHOLD_MS } from "../park.js";
 import { processTable, thisBoot } from "../process-table.js";
 import { attemptEnv } from "./attempt-env.js";
@@ -44,10 +44,6 @@ const FUSERMOUNT = "/usr/bin/fusermount";
 const UMOUNT = "/usr/bin/umount";
 /** How long a stat of the mountpoint may take before its daemon counts as alive but stuck (never removed). */
 const STAT_TIMEOUT_MS = 3_000;
-/** EX_DATAERR: a store behind its seal or a bad run.json (run.ts names it EXIT_DATAERR). */
-const EXIT_DATAERR = 65;
-/** EX_SOFTWARE: the store's head is unreadable (pi's schema moved); run.json says failed, STORE_HEAD_UNREADABLE. */
-const EXIT_SOFTWARE = 70;
 /** Exits a restart cannot fix: 65 data error, 70 store head unreadable, 75 fenced, 76 held. */
 export const TERMINAL_EXITS = [EXIT_DATAERR, EXIT_SOFTWARE, EXIT_FENCED, EXIT_HELD];
 // The package's own CLI, with the extension this module has: `.ts` from a checkout, `.js` once built.

package/dist/place.d.ts

@@ -43,7 +43,6 @@ export type RunnerOrder = {
     env: Record<string, string>;
     stdin?: string;
 };
-/** What the place reads of the run, the way it reads it: `run.json`, and on a disk the run's delegations. */
 /**
  * What the place reads of the run, the way it reads it: `run.json`; on a disk, the run's delegations; and the boxes the
  * place made for its runners, each as a receipt (`HostBox`: provider, kind, from, to, list price per second and where

package/dist/run.d.ts

@@ -3,17 +3,14 @@ import { Harness } 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";
+import { EXIT_DATAERR, EXIT_SOFTWARE, FencedError, PdaError } from "./errors.js";
 import { type ArchilStore, type Profile } from "./store.js";
 import { type ClaimDir, type PersistRecord, type RunRecord, type RunStatus } from "./status.js";
 /** The same-host owner lock under the run's root. */
 export declare const OWNER_LOCK = "owner.lock";
 /** pi's store under the claim's `store/` directory. */
 export declare const STORE_FILE = "run.sqlite";
-/** EX_DATAERR: the run's data refuses to open (a store behind its seal, an unreadable `run.json`); a restart cannot help. */
-export declare const EXIT_DATAERR = 65;
-/** EX_SOFTWARE: this package cannot read the head of pi's store (pi's schema moved); a restart cannot help. */
-export declare const EXIT_SOFTWARE = 70;
+export { EXIT_DATAERR, EXIT_SOFTWARE };
 export type RunErrorCode = "INVALID_ARGUMENT" | "STORE_HEAD_UNREADABLE" | "RUN_RELEASED";
 /**
  * Bad options, a call on a released run, or a store whose head cannot be read (STORE_HEAD_UNREADABLE: the run is marked

package/dist/run.js

@@ -12,7 +12,7 @@ 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 { EXIT_DATAERR, EXIT_FENCED, EXIT_SOFTWARE, FencedError, HeldError, ownWriteFenced, PdaError } from "./errors.js";
 import { openArchilStore } from "./store.js";
 import { LeaseWatchdog } from "./watchdog.js";
 import { currentHolder, DEFAULT_HEARTBEAT_MS, DEFAULT_LEASE_EXPIRY_MS, DEFAULT_LEASE_MARGIN_MS, keepStartMark, openClaimDir, persistRecord, readRunRecord, RUN_JSON, RunRecordError, writeRunRecord, } from "./status.js";
@@ -20,10 +20,7 @@ import { currentHolder, DEFAULT_HEARTBEAT_MS, DEFAULT_LEASE_EXPIRY_MS, DEFAULT_L
 export const OWNER_LOCK = "owner.lock";
 /** pi's store under the claim's `store/` directory. */
 export const STORE_FILE = "run.sqlite";
-/** EX_DATAERR: the run's data refuses to open (a store behind its seal, an unreadable `run.json`); a restart cannot help. */
-export const EXIT_DATAERR = 65;
-/** EX_SOFTWARE: this package cannot read the head of pi's store (pi's schema moved); a restart cannot help. */
-export const EXIT_SOFTWARE = 70;
+export { EXIT_DATAERR, EXIT_SOFTWARE };
 /**
  * Bad options, a call on a released run, or a store whose head cannot be read (STORE_HEAD_UNREADABLE: the run is marked
  * `failed` and released, exit 70).

package/dist/status.js

@@ -7,7 +7,7 @@ import { open, readFile, rename, rm, stat } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { Worker } from "node:worker_threads";
-import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+import { EXIT_DATAERR, 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";
@@ -23,7 +23,7 @@ export const RUN_STATUSES = ["running", "sleeping", "paused", "done", "failed"];
 /** `run.json` is missing a field, has one of the wrong type, or is not JSON. Exit 65 (EX_DATAERR): a restart cannot fix it. */
 export class RunRecordError extends PdaError {
     constructor(message, options = {}) {
-        super("RUN_JSON_INVALID", message, { cause: options.cause, exitCode: 65 });
+        super("RUN_JSON_INVALID", message, { cause: options.cause, exitCode: EXIT_DATAERR });
     }
 }
 const isInstant = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
@@ -184,8 +184,9 @@ export function parseStartMark(text) {
 // 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. 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.
+// that names another (a descriptor number reused) or none is never written, and the keeper stops. A rewrite that fails is
+// checked the same way, so a directory that moved between the check and the write is reported as moved, not as a failed
+// write. Its first failure goes to the main thread, once.
 const KEEPER_SOURCE = `"use strict";
 const fs = require("node:fs");
 const path = require("node:path");
@@ -200,19 +201,23 @@ const report = (message) => {
   reported = true;
   parentPort.postMessage(message);
 };
-function refresh() {
-  if (stopped) return;
+// Why dir is no longer the directory the keeper first saw, or null while it is (the first call records it).
+function moved() {
   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");
+    return "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) {
+  return now.dev === first.dev && now.ino === first.ino ? null : "its directory is no longer the directory the keeper started on";
+}
+function refresh() {
+  if (stopped) return;
+  const away = moved();
+  if (away) {
     stopped = true;
-    return report("its directory is no longer the directory the keeper started on");
+    return report(away);
   }
   let text;
   try {
@@ -245,6 +250,12 @@ function refresh() {
       fs.closeSync(handle);
     }
   } catch (error) {
+    // The directory may have moved after the check above: then that is the reason, and the keeper stops.
+    const away = moved();
+    if (away) {
+      stopped = true;
+      return report(away);
+    }
     report("rewriting it failed (" + (error.code || error.message) + ")");
   }
 }

package/dist/watchdog.d.ts

@@ -18,8 +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. 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.
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup.
  */
 export declare const sweep: (instance: number, options?: SweepOptions) => number;
 /** The main thread's handle on the watchdog thread. */

package/dist/watchdog.js

@@ -30,6 +30,8 @@ function lapsed(shared, now) {
   return true;
 }
 
+// A stat line is "pid (comm) state ppid pgrp ...": its fields are read after the last ")", since comm may hold spaces and
+// parentheses.
 function stat(proc, pid) {
   try {
     const text = fs.readFileSync(path.join(proc, String(pid), "stat"), "utf8");
@@ -126,8 +128,7 @@ export const lapsed = compiled.lapsed;
  * 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. 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.
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup.
  */
 export const sweep = compiled.sweep;
 /** The main thread's handle on the watchdog thread. */

package/package.json

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