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

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## 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.
@@ -513,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/cli.d.ts

@@ -20,8 +20,17 @@ 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;
+/**
+ * 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

@@ -50,7 +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]`;
+                        [--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
@@ -89,20 +91,63 @@ 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());
+/**
+ * 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;
@@ -400,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("=");
@@ -427,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),
         });
     }
@@ -443,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),
@@ -476,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,
@@ -506,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),
@@ -538,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 });
@@ -547,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/hosts/local-host.js

@@ -14,7 +14,7 @@
 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_DATAERR, EXIT_FENCED, EXIT_HELD, EXIT_SOFTWARE, PdaError } from "../errors.js";
@@ -73,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. */
@@ -104,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;
@@ -126,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));
@@ -137,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) {
@@ -165,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}`,
@@ -181,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),
@@ -195,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) {
@@ -288,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);
         },
@@ -313,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;
@@ -329,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)
@@ -352,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");
@@ -362,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "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.",
+  "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",