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

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 0.1.0-beta.26 (2026-10-24)
+
+- Pin the Docker image, planned-move example and live-test sandbox setup to Archil client 0.10.0, with SHA-256 checks for each downloaded package. The client verifies server certificates against the operating system trust store and rejects certificates from the compromised eMudhra intermediate authorities. Linux hosts need client 0.10.0 or later and the operating system CA bundle installed (`ca-certificates` on Debian/Ubuntu); rebuild Docker images and sandbox snapshots to use the new client.
+- Archil's latest SDK: the package depends on the `disk` SDK 1.9.0 (was 1.7.0). The SDK calls the claim, lease and supervisor make are the same in 1.9.0, which adds disk branches and sandbox mounts. The client verbs the package runs take the same arguments in client 0.10.0, whose `mount` adds `--kernel-read-ahead-kb`. A host that installs `disk` itself installs 1.9.0, so npm keeps one copy.
+- `archilPlace({ unheld })` takes a hook that runs in each start's window while nobody holds the run: after ensureRunning's revoke and start mark and after the run's directories are made, before the driver starts anything, once per start. It gets the start's `attempt` and, when the place hands labels over, exactly the `HOST_BOX` that start carries (`start.box`). It also gets the run's own files: `read`, `list`, and `put(path, text)`, which creates a file the run user owns (0644, parents 0755) and refuses a path already there with `EXISTS`. What it returns is added to that start's environment. It needs `ensure.create` and a control that lists. New types `UnheldHook`, `UnheldRun` and `UnheldStart`, and new `unheldTimeoutMs` (default 30 s).
+  - A put the hook does not await still settles inside the window: the driver starts only once every put has settled, within the hook's bound.
+  - `put` is a check, then a write, not a conditional create, so it is not exclusive between two supervisors in one window: put names unique to the start, and bind a shared name in the process that holds the run. It is for non-secret run files; a secret never goes through it.
+  - A start fails, and the driver starts no box, when a put was refused because the run is held (`WINDOW_CLOSED`, even if the hook caught it), when the hook throws a control failure (`CONTROL_API_FAILED`), when it throws anything else or overruns its bound (`UNHELD_FAILED`), or when its environment has a name the start already sets, a name that is not a variable name, a key-shaped name (a `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL` or `CREDENTIALS` segment), or a value that is not a string without NUL (`INVALID_ARGUMENT`, naming the variable, never its value). The caller sees `HOST_START_FAILED` with that `PlaceError` as its cause. `RunFileErrorCode` gains `EXISTS` and `WINDOW_CLOSED`; `PlaceErrorCode` gains `WINDOW_CLOSED`, `CONTROL_API_FAILED` and `UNHELD_FAILED`.
+  - Fix to merged behavior: a box the place already started and its driver adopts again (`adopted: true`, the same attempt started twice) keeps its key in `status().boxes`. New optional `HostDriver.instanceOf(handle)` names the instance a handle is for, the same for its fresh and its adopted handle; `dockerHost` (daemon and container name), `localHost` (host, boot, unit or tag) and `daytonaHost` (sandbox id) implement it, and without it no two handles are one box. It used to get a second entry: a key no runner claimed under `HOST_BOX`, the box counted twice in the receipts, and stopped twice at release.
+- `readRunFile(control, ref, path)` and `listRunFiles(control, ref, dir)` read a run's own files over the disk's control (S3 GET, HEAD and LIST): they never mount, write, or take or wait on the claim, so they read a run another host holds. `readRunFile` returns the bytes, or `null` for a file not written yet; `listRunFiles` returns the names directly under a directory, sorted, names only. Refusals are `RunFileError`: `INVALID_PATH` (before any request: absolute, `.`/`..`, unsafe characters, `.archil/`), `RUN_MISSING`, `NOT_A_FILE` (a directory, or a symlink, decided on Archil's 501 for it, never from a listing, where a symlink looks like an empty file), and `CONTROL_API_FAILED`. Both take a `signal`.
+  - A place offers the same reads of its own run: `Place.readRunFile(path)` and `Place.listRunFiles(dir)`, optional members that `archilPlace` implements over its control and `localPlace` over its run directory on this machine, where a symlink anywhere on the way is `NOT_A_FILE`, never followed. A missing file is `null`; a directory not there yet lists `[]`; every other failure throws.
+  - `INVALID_PATH` names what is wrong with a path (empty, absolute, a `.` or `..` segment, an unsafe character at an index, under `.archil/`), never the path itself.
+  - `archilPlace` tells each host box's runner which label to claim: when its driver makes boxes and names their provider (new optional `HostDriver.provider`; `daytonaHost` names `daytona`) and the place can read the label back (its control lists), each start puts `HOST_BOX` (`{ provider, key, run }`: the box's index in `status().boxes`, the order's `RUN_LABEL`) in that order's environment. With it, `status()` fails (`STATUS_FAILED`) on a box its driver gives no receipt for, instead of shifting the keys of the boxes after it.
+
+## 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 +546,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

@@ -4,7 +4,7 @@ export type RunRef = {
     region: string;
     id: string;
 };
-/** The control-plane calls the claim uses; an archil `Disk` (SDK `disk` 1.7.0) satisfies it. Supervisor side only. */
+/** The control-plane calls the claim uses; an archil `Disk` (SDK `disk` 1.9.0) satisfies it. Supervisor side only. */
 export interface ControlApi {
     putObject(key: string, body: string, options: {
         uid: number;

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/attempt-env.d.ts

@@ -1,3 +1,12 @@
 import type { StartAttempt } from "../supervise.js";
+/** A name an environment variable can have. */
+export declare const ENV_NAME: RegExp;
+/**
+ * Whether `name` is a secret's name: one of its `_`-separated segments, in any case, is KEY, TOKEN, SECRET, PASSWORD,
+ * PASSWD, CREDENTIAL or CREDENTIALS. Segments, not suffixes, so MODAL_TOKEN_ID is one too; CACHE_KEY_PREFIX is refused
+ * as well, and renamed, which is the cheaper error. A start's environment is readable in the instance, so a secret never
+ * goes there.
+ */
+export declare function keyShaped(name: string): boolean;
 /** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
 export declare function attemptEnv(attempt: StartAttempt | undefined, refuse: (message: string) => Error): Record<string, string>;

package/dist/hosts/attempt-env.js

@@ -1,5 +1,16 @@
-const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name an environment variable can have. */
+export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DRIVER_KEYS = new Set(["PATH", "PDA_HOLDER"]);
+const KEY_SEGMENTS = new Set(["KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD", "CREDENTIAL", "CREDENTIALS"]);
+/**
+ * Whether `name` is a secret's name: one of its `_`-separated segments, in any case, is KEY, TOKEN, SECRET, PASSWORD,
+ * PASSWD, CREDENTIAL or CREDENTIALS. Segments, not suffixes, so MODAL_TOKEN_ID is one too; CACHE_KEY_PREFIX is refused
+ * as well, and renamed, which is the cheaper error. A start's environment is readable in the instance, so a secret never
+ * goes there.
+ */
+export function keyShaped(name) {
+    return name.split("_").some((segment) => KEY_SEGMENTS.has(segment.toUpperCase()));
+}
 /** The start's extra environment, checked: PATH, PDA_HOLDER, a name that is not a variable name, or a value with a NUL, is `refuse`'s error. */
 export function attemptEnv(attempt, refuse) {
     const env = attempt?.env ?? {};

package/dist/hosts/daytona.d.ts

@@ -158,7 +158,7 @@ export interface DaytonaHostOptions {
 export declare function sandboxStatus(state: string | undefined): HostStatus | "check";
 /** A Daytona-safe box name for a run: lowercase, at most 63 characters, unique per call. */
 export declare function sandboxName(prefix: string, runId: string, now: number): string;
-export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function daytonaHost(opts: DaytonaHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly fleet: string;
     readonly mountRoot: string;
 };

package/dist/hosts/daytona.js

@@ -293,6 +293,8 @@ export function daytonaHost(opts) {
         fleet,
         mountRoot,
         kills: "box",
+        provider: "daytona",
+        instanceOf: (h) => (h.driver === "daytona" && typeof h.sandboxId === "string" ? `daytona\0${h.sandboxId}` : undefined),
         async start(ref, mountToken, attempt) {
             runPath(ref.id);
             if (!mountToken)

package/dist/hosts/docker.d.ts

@@ -95,7 +95,7 @@ export type ContainerInfo = {
     startedAt: string | null;
     finishedAt: string | null;
 };
-export declare function dockerHost(opts?: DockerHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function dockerHost(opts?: DockerHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly fleet: string;
     readonly mountRoot: string;
     describe(handle: HostHandle): Promise<ContainerInfo | null>;

package/dist/hosts/docker.js

@@ -272,6 +272,7 @@ export function dockerHost(opts = {}) {
         fleet,
         mountRoot,
         kills: "box",
+        instanceOf: (h) => (h.driver === "docker" && typeof h.daemon === "string" && typeof h.name === "string" ? `docker\0${h.daemon}\0${h.name}` : undefined),
         async start(ref, token, attemptInfo) {
             runPath(ref.id);
             if (!opts.image)

package/dist/hosts/local-host.d.ts

@@ -66,7 +66,7 @@ export declare function currentBootId(): string;
 export declare function parseShow(text: string): Record<string, string>;
 /** A unit's state as a host status: loaded and active (or restarting) is running; unloaded is gone. */
 export declare function unitStatus(show: Record<string, string>): HostStatus;
-export declare function localHost(opts?: LocalHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills">> & {
+export declare function localHost(opts?: LocalHostOptions): HostDriver & Required<Pick<HostDriver, "kill" | "kills" | "instanceOf">> & {
     readonly hostName: string;
     readonly mountRoot: string;
 };