@parcha/pi-durable-disk 0.1.0-beta.20 → 0.1.0-beta.23

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.1.0-beta.23 (2026-10-22)
+
+- The CLI's duration flags take a unit: `ms`, `s`, `m` or `h` (`500ms`, `30s`, `1.5m`, `1h`). A bare number used to mean milliseconds, so `--every 90` ran every 90 ms. It is now refused with exit 2 and a hint: `not a duration: "90": give a unit, e.g. 90s or 90ms`. Every duration flag a command is given is checked before the command acts. **Who breaks:** a script or service unit that passes a bare number to `--park-threshold`, `--park-idle`, `--drain-timeout`, `--stop-timeout`, `--control-timeout`, `--lease-expiry`, `--stonith-timeout`, `--start-grace`, `--start-backoff-max`, `--token-grace` or `--every`. **What to do:** add the unit you meant (`90ms` keeps today's behaviour).
+  - Flags named -ms keep bare milliseconds (`--heartbeat-ms`, `--lease-expiry-ms`, `--lease-margin-ms`): their name carries the unit, and units are still accepted.
+  - A bare `0` still turns off `--park-threshold` (no parking), `--start-grace` (no grace, so no backoff) and `--start-backoff-max` (no backoff). Elsewhere `0` takes a unit (`0s`) and behaves as before.
+- **SECURITY: `localHost` stops and kills only a unit it could have started, and says so when it refuses one.** A handle comes back from `run.json`, which the run's user can write, and `stop` and `kill` act on it as root (`systemctl stop` and `kill`, `archil unmount`, `fusermount`, `umount`, `rmdir`). Before, only the shape of the unit's name was checked, so a handle that named another service on the host had it stopped. Now `stop` and `kill` act only on a unit with the driver's `unitPrefix` whose mountpoint is one run's under the driver's mount root, as `dockerHost` and `daytonaHost` act only on their fleet's. For any other handle of this host and boot, and for a child-mode handle whose pid is 1 or below or that has no start ticks, they throw `INVALID_ARGUMENT`, naming the handle and saying that nothing was stopped or killed. `supervise` logs that STONITH as `failed` with the reason, where it used to log `stopped`, then revokes and starts as before. A handle of another host or boot, and a child that is already gone, are still no-ops; `status` is unchanged.
+
+  - Who notices: a supervisor that changed `--unit-prefix` or `--mount-root` between runs no longer stops the units started under the old values. Their STONITH logs the refusal, and the revoke fences them as before.
+- **SECURITY: `localHost` and `archilEnv` refuse to run the agent as root.** The docs say instances and the agent's tools never run as root, and `--run-as`, `daytonaHost` and the in-box launcher already refused uid 0. `localHost` only required a `user` when the supervisor runs as root, so `user: "root"`, `"0"` or `0` started the unit with `User=0`, and child mode in a root process ran the instance as root; `archilEnv` accepted `runAs: { uid: 0 }`. Now `localHost.start` throws `INVALID_ARGUMENT` for a user that is uid 0 (a name is looked up in `/etc/passwd`) or empty (systemd runs a unit with an empty `User=` as root), and for child mode in a root process, and `archilEnv` throws `INVALID_RUN_AS` for a `runAs` uid of 0, each before anything runs. A driver is constructed as before, so the `status` command's read-only driver is unaffected.
+- **SECURITY: `localHost` in systemd mode no longer puts the instance environment on the `systemd-run` command line, which sudo logged to the journal and `systemctl show` exposed; it passes it through a root-only file.**
+  - Before, each variable of the driver's `env` and of a start's own environment (`StartAttempt.env`) went to `systemd-run` as `--setenv=NAME=value`, under `sudo -n`. `sudo` logs the whole command line to the journal, and `--setenv` is stored in the unit's `Environment=` property, which any local user reads with `systemctl show`. A secret in either place was in both. The mount token and the API key were never affected: the token travels on stdin and the API key never reaches the driver.
+  - Now the environment is written to a root-only (mode 0600) file beside the mount token's, through stdin, and the unit loads it with `-p EnvironmentFile=<path>`. No value is on any argument. The file lives as long as the unit may restart (a restart in place loads it again). It is removed when the unit is stopped, when a start fails, and by the unit itself (`ExecStopPost=`) when it ends for good: a park or a finish, or a terminal exit. A unit that systemd gave up restarting keeps it until `stop`. A value with a newline, a carriage return or a NUL, or a name that is not a variable name, is refused with `INVALID_ARGUMENT` before anything runs, rather than written mangled.
+  - A deployment that put a secret in `localHost`'s `env` or in `StartAttempt.env` under systemd mode should treat it as exposed to anyone who could read its journal or run `systemctl show` on the unit, and rotate it. Child mode is unaffected: its environment goes in `spawn`'s `env`.
+- Every install line in the README and the examples pins `@earendil-works/pi-durable`, `@earendil-works/pi-ai` and `@earendil-works/chord` at 1.3.0. pi 1.4.0 is now npm's `latest`, and an unpinned line ends in ERESOLVE against the peer ranges (`>=1.0.4 <1.4.0`). pi 1.4 is not supported yet; a later release widens the range.
+- The README opens with the agent as the workspace, and the package description is its short form: its conversation and its files live together in
+  one directory on a disk, which any Linux host or container can mount, release and mount somewhere else, and the agent carries on
+  where the last host released it. The second paragraph says what opening and releasing a run do on an Archil disk (mount and
+  claim, then seal, give up the claim and unmount) and on a plain directory (no mount).
+
+## 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.
@@ -509,7 +532,6 @@ published.
 - Unchanged, because they name the Archil disk: `bin/archil-scoped` (and the `./bin/archil-scoped` export), `ARCHIL_API_KEY`, `archilEnv`,
   `ArchilCodingTools`, the claim's internals and the `archil` client it runs.
 
-
 **A holder the control API lists without a path**
 - Archil's control API resolves a delegation's path best-effort and can list one with no path, live or orphaned, even on a
   run id used once. `findDelegations` matched by path only, so such a holder read as none everywhere it is used

package/README.md

@@ -1,10 +1,12 @@
 # @parcha/pi-durable-disk
 
-Run a [pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable) agent from a directory or a network disk, so any process or host can open the run and carry on where the last one released it.
+The agent is the workspace: its conversation and its files live together in one directory on a disk. Mount the disk on any Linux host or container, release it, and mount it somewhere else: the agent carries on where the last host released it.
 
-An agent's home and its runs live on the disk, not on a machine: the conversation, the agent's files and what it was waiting
-for are all in the run's directory, so a process is somewhere a run visits, not where it lives. This is a beta
-(`0.1.0-beta.N`): a change that breaks a caller is listed in [CHANGELOG.md](CHANGELOG.md) when it ships.
+On an [Archil](https://archil.com) disk, opening a run mounts its directory (`runs/<id>` of the disk) and takes an exclusive claim on it, and `release()` seals the
+run, gives up the claim and unmounts. On a plain directory of this machine (`localRun`) there is no mount: one machine, no disk,
+no key. It runs [pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable) agents, on Linux (macOS is for development;
+Windows is not supported). This is a beta (`0.1.0-beta.N`): a change that breaks a caller is listed in [CHANGELOG.md](CHANGELOG.md)
+when it ships.
 
 ## What it is
 
@@ -42,9 +44,11 @@ Archil is not supported: the package needs the disk to give an exclusive claim a
 On Linux with Node 22.19 or later (or on macOS [for development](docs/reference.md#on-macos)). In an empty directory:
 
 ```sh
-npm install @parcha/pi-durable-disk@beta @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
+npm install @parcha/pi-durable-disk@beta @earendil-works/pi-durable@1.3.0 @earendil-works/pi-ai@1.3.0 @earendil-works/chord@1.3.0
 ```
 
+pi 1.4 is not supported yet; a later release widens the range.
+
 Save this as `pick-up.mts` (Node 22.19 or later runs the types away; `.mts` makes it an ES module whatever your
 `package.json` says). It is [examples/pick-up-a-run/main.ts](examples/pick-up-a-run/main.ts). It starts three processes, one after another, on
 one directory. Each opens the run, answers one question of the same chat, and releases it. pi-ai's faux model answers, so it
@@ -216,11 +220,11 @@ what it imports.
 ## Install
 
 ```sh
-npm install @parcha/pi-durable-disk@beta @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
+npm install @parcha/pi-durable-disk@beta @earendil-works/pi-durable@1.3.0 @earendil-works/pi-ai@1.3.0 @earendil-works/chord@1.3.0
 ```
 
-`@earendil-works/pi-durable` and `@earendil-works/chord` are peer dependencies, `>=1.0.4 <1.4.0`. Node 22.19 or later;
-Linux, or macOS for development.
+`@earendil-works/pi-durable` and `@earendil-works/chord` are peer dependencies, `>=1.0.4 <1.4.0`: pi 1.4 is not supported yet; a
+later release widens the range. Node 22.19 or later; Linux, or macOS for development.
 
 From a checkout (this package is `packages/pi-durable-disk` of the repository; the root build compiles `dist/`):
 

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,7 +20,17 @@ export declare function watchdogOwnsCgroup(holder: Record<string, unknown>, opti
     owns: boolean;
     warning?: string;
 };
-export declare function parseDuration(text: string): number;
+/**
+ * A duration: a number and its unit, `ms`, `s`, `m` or `h` ("500ms", "30s", "1.5m", "1h"). A bare number is refused with
+ * a hint, so "90" is never silently 90 ms. A flag whose name carries its unit (`bareMs`, the `-ms` flags) takes a bare
+ * number as milliseconds; a flag whose 0 turns its feature off (`zeroOff`) also takes a bare `0`.
+ */
+export declare function parseDuration(text: string, rule?: DurationRule): number;
+/** How a duration flag reads a bare number: as milliseconds (`bareMs`), or a bare `0` as off (`zeroOff`); otherwise never. */
+export type DurationRule = {
+    readonly bareMs?: boolean;
+    readonly zeroOff?: boolean;
+};
 /** `--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): {
     uid: number;

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]
@@ -50,8 +50,9 @@ const USAGE = `usage:
   pi-durable-disk status --disk D --region R --id ID [--host-name NAME] [--api-key-env NAME] [--docker BIN]
   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. */
+                        [--api-key-env NAME]
+durations take a unit (500ms, 30s, 1.5m, 1h); flags named -ms take bare milliseconds; a bare 0 turns off
+--park-threshold, --start-grace and --start-backoff-max`;
 /**
  * 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,19 +91,63 @@ export function watchdogOwnsCgroup(holder, options = {}) {
         return refuse(`the parent shares cgroup ${own}, so this process only inherited the handle`);
     return { owns: true };
 }
-export function parseDuration(text) {
-    const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(text.trim());
+/**
+ * A duration: a number and its unit, `ms`, `s`, `m` or `h` ("500ms", "30s", "1.5m", "1h"). A bare number is refused with
+ * a hint, so "90" is never silently 90 ms. A flag whose name carries its unit (`bareMs`, the `-ms` flags) takes a bare
+ * number as milliseconds; a flag whose 0 turns its feature off (`zeroOff`) also takes a bare `0`.
+ */
+export function parseDuration(text, rule = {}) {
+    const t = text.trim();
+    const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(t);
     if (!m)
-        throw new UsageError(`not a duration: ${text}`);
-    return Math.round(Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[(m[2] ?? "ms")]);
+        throw new UsageError(`not a duration: "${text}": a number and its unit (ms, s, m or h), e.g. 90s`);
+    if (m[2] === undefined) {
+        if (rule.bareMs)
+            return Math.round(Number(m[1]));
+        if (rule.zeroOff && Number(m[1]) === 0)
+            return 0;
+        throw new UsageError(`not a duration: "${text}": give a unit, e.g. ${t}s or ${t}ms`);
+    }
+    return Math.round(Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2]]);
+}
+/**
+ * Every duration flag of every command, with its rule. The `-ms` flags carry their unit in their name. A bare `0` turns
+ * off parking (`--park-threshold`), the start grace and its backoff (`--start-grace`), and the backoff alone
+ * (`--start-backoff-max`, the grace then stays at `--start-grace`).
+ */
+const DURATION_FLAGS = {
+    "heartbeat-ms": { bareMs: true },
+    "lease-expiry-ms": { bareMs: true },
+    "lease-margin-ms": { bareMs: true },
+    "park-threshold": { zeroOff: true },
+    "park-idle": {},
+    "drain-timeout": {},
+    "stop-timeout": {},
+    "control-timeout": {},
+    "lease-expiry": {},
+    "stonith-timeout": {},
+    "start-grace": { zeroOff: true },
+    "start-backoff-max": { zeroOff: true },
+    "token-grace": {},
+    every: {},
+};
+/** A duration flag's value in milliseconds, by the flag's rule; undefined when the flag is absent. */
+function durationFlag(values, name) {
+    const value = values[name];
+    return typeof value === "string" ? parseDuration(value, DURATION_FLAGS[name]) : undefined;
 }
 function parse(argv, options) {
+    let values;
     try {
-        return parseArgs({ args: argv, options, allowPositionals: false, strict: true }).values;
+        values = parseArgs({ args: argv, options, allowPositionals: false, strict: true }).values;
     }
     catch (err) {
         throw new UsageError(err.message);
     }
+    // Every duration flag given is checked here, before the command does anything with any of them.
+    for (const name of Object.keys(DURATION_FLAGS))
+        durationFlag(values, name);
+    return values;
 }
 /** A user or group name or number, as a number (from /etc/passwd or /etc/group). */
 function idOf(value, file, fallback) {
@@ -206,7 +251,7 @@ async function runInstance(values) {
     const onSigterm = str(values["on-sigterm"], "resume");
     if (onSigterm !== "resume" && onSigterm !== "pause")
         throw new UsageError("--on-sigterm is resume or pause");
-    const ms = (name) => (typeof values[name] === "string" ? parseDuration(values[name]) : undefined);
+    const ms = (name) => durationFlag(values, name);
     const lease = { heartbeatMs: ms("heartbeat-ms"), expiryMs: ms("lease-expiry-ms"), marginMs: ms("lease-margin-ms") };
     const parkMs = ms("park-threshold") || undefined;
     const drainMs = ms("drain-timeout") ?? 0;
@@ -219,7 +264,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.
@@ -398,7 +445,7 @@ export function instanceRunArgs(values) {
     return [...(typeof values.app === "string" ? ["--app", resolve(values.app)] : []), ...(values["run-arg"] ?? [])];
 }
 /** `--park-threshold` for either driver: absent keeps the driver's default, 0 turns parking off. */
-const parkThreshold = (values) => values["park-threshold"] === undefined ? {} : { parkThresholdMs: parseDuration(str(values["park-threshold"])) || null };
+const parkThreshold = (values) => values["park-threshold"] === undefined ? {} : { parkThresholdMs: durationFlag(values, "park-threshold") || null };
 function driverFrom(values) {
     const env = Object.fromEntries((values.env ?? []).map((kv) => {
         const i = kv.indexOf("=");
@@ -425,7 +472,7 @@ function driverFrom(values) {
             dockerArgs: values["docker-arg"] ?? [],
             apparmor: apparmor === "none" ? false : apparmor,
             note: (line) => emit({ event: "docker", note: line }),
-            stopTimeoutMs: values["stop-timeout"] ? parseDuration(str(values["stop-timeout"])) : undefined,
+            stopTimeoutMs: values["stop-timeout"] ? durationFlag(values, "stop-timeout") : undefined,
             ...parkThreshold(values),
         });
     }
@@ -441,7 +488,7 @@ function driverFrom(values) {
         user: str(values.user),
         group: str(values.group),
         runArgs,
-        stopTimeoutMs: values["stop-timeout"] ? parseDuration(str(values["stop-timeout"])) : undefined,
+        stopTimeoutMs: values["stop-timeout"] ? durationFlag(values, "stop-timeout") : undefined,
         restart: values["no-restart"] ? false : undefined,
         logDir: str(values["log-dir"]),
         archil: str(values.archil),
@@ -474,7 +521,7 @@ async function supervise(values) {
     if (docker && (typeof values.image !== "string" || !values.image))
         throw new UsageError("--host docker needs --image");
     const disk = await cliControl(values);
-    const controlTimeoutMs = values["control-timeout"] ? parseDuration(str(values["control-timeout"])) : CONTROL_TIMEOUT_MS;
+    const controlTimeoutMs = values["control-timeout"] ? durationFlag(values, "control-timeout") : CONTROL_TIMEOUT_MS;
     if (values.check) {
         const report = await checkHost({
             control: disk,
@@ -504,10 +551,10 @@ async function supervise(values) {
     const host = driverFrom(values);
     const opts = {
         control: disk,
-        leaseExpiryMs: values["lease-expiry"] ? parseDuration(str(values["lease-expiry"])) : undefined,
-        stonithTimeoutMs: values["stonith-timeout"] ? parseDuration(str(values["stonith-timeout"])) : undefined,
-        startGraceMs: values["start-grace"] !== undefined ? parseDuration(str(values["start-grace"])) : undefined,
-        startBackoffMaxMs: values["start-backoff-max"] !== undefined ? parseDuration(str(values["start-backoff-max"])) : undefined,
+        leaseExpiryMs: values["lease-expiry"] ? durationFlag(values, "lease-expiry") : undefined,
+        stonithTimeoutMs: values["stonith-timeout"] ? durationFlag(values, "stonith-timeout") : undefined,
+        startGraceMs: durationFlag(values, "start-grace"),
+        startBackoffMaxMs: durationFlag(values, "start-backoff-max"),
         tokenTtl: str(values["token-ttl"]),
         tokenPrefix: str(values["token-prefix"]),
         demand: Boolean(values.demand),
@@ -536,7 +583,7 @@ async function supervise(values) {
             prefix: str(values["token-prefix"], TOKEN_PREFIX),
             runs: values.id ? refs.map((x) => x.id) : undefined,
             expired: Boolean(values["sweep-tokens"]),
-            graceMs: values["token-grace"] ? parseDuration(str(values["token-grace"])) : undefined,
+            graceMs: values["token-grace"] ? durationFlag(values, "token-grace") : undefined,
         }).catch((e) => ({ removed: [], failed: [{ identifier: "*", error: e.message }] }));
         if (r.removed.length || r.failed.length)
             emit({ event: "token-sweep", ...r });
@@ -545,7 +592,7 @@ async function supervise(values) {
         await tick();
         return failures ? 1 : 0;
     }
-    const every = parseDuration(str(values.every));
+    const every = durationFlag(values, "every");
     let stopped = false;
     process.once("SIGTERM", () => (stopped = true));
     process.once("SIGINT", () => (stopped = true));

package/dist/env.js

@@ -510,6 +510,9 @@ export function archilEnv(claim, options = {}) {
     if (runAs && ![runAs.uid, runAs.gid].every((n) => Number.isSafeInteger(n) && n >= 0)) {
         throw new EnvError("INVALID_RUN_AS", `runAs needs a numeric uid and gid, got ${JSON.stringify(runAs)}`);
     }
+    if (runAs?.uid === 0) {
+        throw new EnvError("INVALID_RUN_AS", "runAs names root (uid 0): the agent's commands would run as the owner of run.json, the store and the archil daemon");
+    }
     const darwin = process.platform === "darwin";
     const noNewPrivs = options.noNewPrivs ?? !darwin;
     const setpriv = noNewPrivs || runAs ? requireSetpriv(options.setprivPath ?? SETPRIV) : undefined;

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

@@ -14,10 +14,10 @@
 import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
-import { extname, join } from "node:path";
+import { basename, 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.
@@ -77,6 +73,14 @@ export function currentBootId() {
         throw new Error("this machine's boot id cannot be read");
     return boot;
 }
+/** The uid a user number or name stands for (a name through /etc/passwd), or undefined when nothing names it. */
+async function uidOf(user) {
+    if (/^\d+$/.test(user))
+        return Number(user);
+    const rows = await readFile("/etc/passwd", "utf8").then((text) => text.split("\n").map((line) => line.split(":")), () => []);
+    const row = rows.find((fields) => fields.length >= 3 && fields[0] === user);
+    return row ? Number(row[2]) : undefined;
+}
 const firstLine = (r) => (r.stderr.trim().split("\n").at(-1) ?? "").slice(0, 300);
 const okRan = (r) => r.code === 0 && !r.timedOut;
 /** `systemctl show` output as a map. */
@@ -108,6 +112,35 @@ export function unitStatus(show) {
             return "unknown";
     }
 }
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The text of an `EnvironmentFile=`: one `NAME="value"` line each, with `\` and `"` escaped inside the double quotes (nothing
+ * else is special there: systemd expands no `$` in this file). A name that is not a variable name, or a value with a newline,
+ * a carriage return or a NUL, cannot be written faithfully, so it is refused rather than mangled.
+ */
+/**
+ * The unit's own `ExecStopPost=` (`+`: as root, whatever `User=` is) that removes its environment file when the unit ends for
+ * good, so an instance that parks or finishes on its own leaves nothing behind. A restart in place loads the file again, so it
+ * stays after any exit systemd will restart: with `Restart=on-failure`, one that is not `success` and not in `TERMINAL_EXITS`.
+ * (`$$` is systemd's escape for `$`; it hands the script `SERVICE_RESULT` and `EXIT_STATUS`.)
+ */
+function environmentCleanup(path, restarts) {
+    if (!restarts)
+        return `+/bin/rm -f ${path}`;
+    const final = ["success:*", ...TERMINAL_EXITS.map((code) => `exit-code:${code}`)].join("|");
+    return `+/bin/sh -c 'case "$$SERVICE_RESULT:$$EXIT_STATUS" in ${final}) /bin/rm -f "$$1";; esac' sh ${path}`;
+}
+function environmentFile(env) {
+    const lines = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (!ENV_NAME.test(name))
+            throw new LocalHostError("INVALID_ARGUMENT", `${JSON.stringify(name)} is not an environment variable name`);
+        if (typeof value !== "string" || /[\r\n\0]/.test(value))
+            throw new LocalHostError("INVALID_ARGUMENT", `the value of ${name} is not a string without a newline, a carriage return or a NUL`);
+        lines.push(`${name}="${value.replace(/[\\"]/g, "\\$&")}"`);
+    }
+    return `${lines.join("\n")}\n`;
+}
 export function localHost(opts = {}) {
     const mode = opts.mode ?? "systemd";
     const mountRoot = opts.mountRoot ?? DEFAULT_MOUNT_ROOT;
@@ -130,6 +163,28 @@ export function localHost(opts = {}) {
     const procMounts = opts.procMounts ?? "/proc/self/mounts";
     const mine = (h) => h.driver === "local" && h.host === hostName;
     const mountpointOf = (ref) => join(mountRoot, runPath(ref.id));
+    const runMountpoint = (mp) => {
+        try {
+            return mp === join(mountRoot, runPath(basename(mp)));
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * The unit of a systemd handle this driver could have made: a safe name with its prefix, whose mountpoint is one run's
+     * under its mount root; undefined for any other. A handle comes back from run.json, which the run's user can write, and
+     * stop and kill act on it as root (systemctl, unmount, rmdir), as the docker and daytona drivers act only on their fleet's.
+     * They refuse any other with the reason, so a supervisor's log never reports a stop that did not happen.
+     */
+    const ownUnit = (h) => {
+        const { unit, mountpoint } = h;
+        if (typeof unit !== "string" || !UNIT_SAFE.test(unit) || !unit.startsWith(prefix))
+            return undefined;
+        return typeof mountpoint === "string" && runMountpoint(mountpoint) ? unit : undefined;
+    };
+    const notOwnUnit = (h, what) => new LocalHostError("INVALID_ARGUMENT", `the handle's unit ${JSON.stringify(h.unit)} at ${JSON.stringify(h.mountpoint)} is not one this driver starts (${prefix}<run id>-<stamp>, a run's mountpoint under ${mountRoot}): nothing ${what}`);
+    const notOwnPid = (h, what) => new LocalHostError("INVALID_ARGUMENT", `the handle names pid ${JSON.stringify(h.pid)} with start ticks ${JSON.stringify(h.startTicks)}, not a process this driver started: nothing ${what}`);
     const mounted = async (mp) => (await readFile(procMounts, "utf8")).split("\n").some((l) => l.split(" ")[1] === mp);
     const parkMs = opts.parkThresholdMs === undefined ? LOCAL_PARK_THRESHOLD_MS : opts.parkThresholdMs;
     const drainMs = Math.max(0, stopTimeoutMs - Math.min(5_000, stopTimeoutMs / 2));
@@ -141,15 +196,18 @@ export function localHost(opts = {}) {
     ];
     const holderEnv = (h) => JSON.stringify(h);
     const tokenFile = (unit) => join(TOKEN_DIR, `${unit}.mount-token`);
-    async function writeTokenFile(path, token) {
+    /** The unit's environment, loaded with `EnvironmentFile=`: a value on `systemd-run`'s argv is logged by sudo and shown by `systemctl show`. */
+    const envFile = (unit) => join(TOKEN_DIR, `${unit}.env`);
+    /** Writes a root-only (0600) file under the token directory; `content` goes through stdin, never an argument. */
+    async function writeSecretFile(path, content, what) {
         if (!sudo) {
             await mkdir(TOKEN_DIR, { recursive: true, mode: 0o700 });
-            await writeFile(path, token, { mode: 0o600 });
+            await writeFile(path, content, { mode: 0o600 });
             return;
         }
-        const r = await root(["/bin/sh", "-c", 'umask 077 && mkdir -p "$1" && cat > "$2"', "sh", TOKEN_DIR, path], { input: token });
+        const r = await root(["/bin/sh", "-c", 'umask 077 && mkdir -p "$1" && cat > "$2"', "sh", TOKEN_DIR, path], { input: content });
         if (!okRan(r))
-            throw new LocalHostError("START_FAILED", `cannot write the mount token file: ${firstLine(r)}`);
+            throw new LocalHostError("START_FAILED", `cannot write the ${what}: ${firstLine(r)}`);
     }
     /** Replace the token file by an empty one: the started instance's open fd keeps the token, the path no longer has it. */
     async function emptyTokenFile(path) {
@@ -169,10 +227,13 @@ export function localHost(opts = {}) {
         const mountpoint = mountpointOf(ref);
         const handle = { driver: "local", mode: "systemd", host: hostName, bootId, unit, mountpoint };
         const env = { ...opts.env, ...extra, PATH: SAFE_PATH, PDA_HOLDER: holderEnv(handle) };
+        const environment = environmentFile(env);
         const path = tokenFile(unit);
-        await writeTokenFile(path, token);
+        const envPath = envFile(unit);
+        await writeSecretFile(path, token, "mount token file");
         let started = false;
         try {
+            await writeSecretFile(envPath, environment, "environment file");
             const argv = [
                 SYSTEMD_RUN,
                 `--unit=${unit}`,
@@ -185,7 +246,8 @@ export function localHost(opts = {}) {
                 "-p", `User=${user}`,
                 "-p", `Group=${group}`,
                 "-p", `StandardInput=file:${path}`,
-                ...Object.entries(env).map(([k, v]) => `--setenv=${k}=${v}`),
+                "-p", `EnvironmentFile=${envPath}`,
+                "-p", `ExecStopPost=${environmentCleanup(envPath, opts.restart !== false)}`,
                 "--",
                 ...command,
                 ...runFlags(ref),
@@ -199,8 +261,13 @@ export function localHost(opts = {}) {
         }
         finally {
             // Type=exec: systemd-run returns after the exec, so the instance's stdin is already open on the token. The path
-            // stays (empty) because a restart in place opens it again; stop removes it.
-            await (started ? emptyTokenFile(path) : removeFile(path)).catch(() => { });
+            // stays (empty) because a restart in place opens it again; stop removes it. The environment file stays whole: a
+            // restart in place loads it again, and stop removes it. The unit's ExecStopPost removes the file when
+            // it ends for good (a park, a finish, a terminal exit). A start that failed leaves neither.
+            if (started)
+                await emptyTokenFile(path).catch(() => { });
+            else
+                await Promise.all([removeFile(path), removeFile(envPath)]).catch(() => { });
         }
     }
     async function startChild(ref, token, extra) {
@@ -292,6 +359,17 @@ export function localHost(opts = {}) {
         kills: "process",
         async start(ref, token, attempt) {
             runPath(ref.id);
+            // Never as root: the instance and the agent's tools would share a uid with the archil daemon that holds the mount
+            // token, and own run.json and the store outright.
+            if (mode === "systemd" && user.trim() === "") {
+                throw new LocalHostError("INVALID_ARGUMENT", "the user is empty, and systemd runs a unit with an empty User= as root: name the unprivileged user the instance runs as (user)");
+            }
+            if (mode === "systemd" && (await uidOf(user)) === 0) {
+                throw new LocalHostError("INVALID_ARGUMENT", `user ${user} is root: name the unprivileged user the instance runs as (user)`);
+            }
+            if (mode === "child" && process.getuid?.() === 0) {
+                throw new LocalHostError("INVALID_ARGUMENT", "child mode runs the instance as this process's user, which is root: use systemd mode with a user");
+            }
             const extra = attemptEnv(attempt, (m) => new LocalHostError("INVALID_ARGUMENT", m));
             return mode === "systemd" ? startUnit(ref, token, extra) : startChild(ref, token, extra);
         },
@@ -317,7 +395,7 @@ export function localHost(opts = {}) {
                 // real process, then. A pid of 1 or below names a group (`kill(-0)` is this supervisor's own, `kill(-1)` every
                 // process it may signal), and without start ticks nothing tells a reused pid from the instance.
                 if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
-                    return;
+                    throw notOwnPid(h, "stopped");
                 const alive = () => procStartTicks(pid) === h.startTicks;
                 if (!alive())
                     return;
@@ -333,22 +411,24 @@ export function localHost(opts = {}) {
                     process.kill(-pid, "SIGKILL");
                 return;
             }
-            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
-                return;
-            const stopUnit = () => root([SYSTEMCTL, "stop", `${h.unit}.service`], { timeoutMs: stopTimeoutMs + 10_000 });
+            const unit = ownUnit(h);
+            if (unit === undefined)
+                throw notOwnUnit(h, "stopped");
+            const stopUnit = () => root([SYSTEMCTL, "stop", `${unit}.service`], { timeoutMs: stopTimeoutMs + 10_000 });
             let r = await stopUnit();
-            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
+            if (!okRan(r) && unitStatus(await show(unit)) === "running") {
                 // A unit that outlives SIGKILL is wedged in its mount (a FUSE request its daemon never answers): kill the
                 // daemon so those requests fail and the processes can die, then stop once more.
-                await killDaemons(h.unit);
+                await killDaemons(unit);
                 r = await stopUnit();
-                if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
-                    throw new LocalHostError("STOP_FAILED", `systemctl stop ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+                if (!okRan(r) && unitStatus(await show(unit)) === "running") {
+                    throw new LocalHostError("STOP_FAILED", `systemctl stop ${unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
                 }
             }
-            await cleanMount(h.unit, String(h.mountpoint));
-            await root([SYSTEMCTL, "reset-failed", `${h.unit}.service`]);
-            await removeFile(tokenFile(h.unit));
+            await cleanMount(unit, String(h.mountpoint));
+            await root([SYSTEMCTL, "reset-failed", `${unit}.service`]);
+            await removeFile(tokenFile(unit));
+            await removeFile(envFile(unit));
         },
         async kill(h) {
             if (!mine(h) || h.bootId !== bootId)
@@ -356,7 +436,9 @@ export function localHost(opts = {}) {
             if (h.mode === "child") {
                 const pid = Number(h.pid);
                 // As in stop: only a real process, and only the one the handle names (its start ticks).
-                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number" || procStartTicks(pid) !== h.startTicks)
+                if (!Number.isInteger(pid) || pid <= 1 || typeof h.startTicks !== "number")
+                    throw notOwnPid(h, "killed");
+                if (procStartTicks(pid) !== h.startTicks)
                     return;
                 try {
                     process.kill(-pid, "SIGKILL");
@@ -366,13 +448,14 @@ export function localHost(opts = {}) {
                 }
                 return;
             }
-            if (typeof h.unit !== "string" || !UNIT_SAFE.test(h.unit))
-                return;
+            const unit = ownUnit(h);
+            if (unit === undefined)
+                throw notOwnUnit(h, "killed");
             // Every process of the unit's control group at once, the instance's commands included. Its FUSE daemon runs in a
             // scope of its own and keeps the mount, as after an OOM kill; the unit restarts in place unless restart is off.
-            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${h.unit}.service`]);
-            if (!okRan(r) && unitStatus(await show(h.unit)) === "running") {
-                throw new LocalHostError("KILL_FAILED", `systemctl kill ${h.unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
+            const r = await root([SYSTEMCTL, "kill", "--signal=SIGKILL", "--kill-whom=all", `${unit}.service`]);
+            if (!okRan(r) && unitStatus(await show(unit)) === "running") {
+                throw new LocalHostError("KILL_FAILED", `systemctl kill ${unit}: ${r.timedOut ? "timed out" : firstLine(r)}`);
             }
         },
     };

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));

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,7 +1,7 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.20",
-  "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
+  "version": "0.1.0-beta.23",
+  "description": "The agent is the workspace: its conversation and its files live together in one directory on a disk. Mount it on any Linux host or container, release it, and mount it elsewhere: the agent carries on.",
   "keywords": [
     "pi",
     "pi-durable",