@williamthorsen/nmr 2.1.0 → 2.2.0

package/.meta/changelog.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "2.2.0",
+    "date": "2026-11-12",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Makes each `nmr` delegation remove, before it pushes, the host's other checkouts that have gone unused for longer than the new user-config key `delegate.removeCheckoutsAfterDays` allows (7 days by default, `false` to keep them), while keeping any checkout whose lock has a live holder. (#1317)",
+            "hash": "529687fecf5111851cb369c5ee9554d9711dad62",
+            "entry": 1
+          },
+          {
+            "description": "Adds to the failure message of a delegation step that fails with `No space left on device` whether the host's filesystem ran out of inodes or of space. (#1317)",
+            "hash": "529687fecf5111851cb369c5ee9554d9711dad62",
+            "entry": 2
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "2.1.0",
     "date": "2026-11-12",

package/.readyup/kits/default.js

@@ -9662,7 +9662,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "2.1.0" };
+  const pickedFields = { "version": "2.2.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -31,7 +31,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 2.1.0",
+            "@williamthorsen/nmr >= 2.2.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -235,7 +235,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "5277f03b",
+          "hash": "7015d006",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -363,7 +363,7 @@
       "readyupVersion": "0.46.1",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "70e833f9"
+      "targetHash": "177bd0ca"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.2.0 — 2026-11-12
+
+### 🎉 Features
+
+- Makes each `nmr` delegation remove, before it pushes, the host's other checkouts that have gone unused for longer than the new user-config key `delegate.removeCheckoutsAfterDays` allows (7 days by default, `false` to keep them), while keeping any checkout whose lock has a live holder. (#1317)
+- Adds to the failure message of a delegation step that fails with `No space left on device` whether the host's filesystem ran out of inodes or of space. (#1317)
+
 ## 2.1.0 — 2026-11-12
 
 ### 🎉 Features

package/README.md

@@ -5,15 +5,12 @@
 Context-aware script runner for pnpm monorepos. Includes an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v2.1.0 (2026-11-12)
+## Release notes — v2.2.0 (2026-11-12)
 
 ### 🎉 Features
 
-- Adds the `fanOut.extraSortedCommands` root-config key, which lists commands besides `build` whose fan-out keeps the topological order, and nmr rejects a name in it that does not resolve to any command when it loads the config. (#1306)
-
-### ⚡ Performance
-
-- Drops pnpm's topological sort, which runs each package only after its workspace dependencies finish, from every `-R` and `-F` fan-out except one of `build`, so that `nmr test`, the `test:*` commands, and `nmr typecheck` start each package without waiting for its workspace dependencies. (#1306)
+- Makes each `nmr` delegation remove, before it pushes, the host's other checkouts that have gone unused for longer than the new user-config key `delegate.removeCheckoutsAfterDays` allows (7 days by default, `false` to keep them), while keeping any checkout whose lock has a live holder. (#1317)
+- Adds to the failure message of a delegation step that fails with `No space left on device` whether the host's filesystem ran out of inodes or of space. (#1317)
 <!-- /section:release-notes -->
 
 ## Installation

package/dist/esm/delegation/delegate-host.js

@@ -13,7 +13,7 @@ import { createSnapshot } from "./createSnapshot.js";
 import { chooseHost, probeHost } from "./remote-probe.js";
 import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG, DELEGATION_FAILURE_EXIT_CODE, deriveCheckoutPath, formatMisplacedDelegationWarning, readLastLine, runRemotely, } from "./remote-run.js";
 import { resolveDelegationTarget } from "./resolveDelegationTarget.js";
-import { formatDisplayPath, loadUserConfig } from "./user-config.js";
+import { DEFAULT_REMOVE_CHECKOUTS_AFTER_DAYS, formatDisplayPath, loadUserConfig } from "./user-config.js";
 export async function resolveExecutionTarget(invocation) {
     const { command, context, env, parsedArgs, stderr, styles } = invocation;
     if (parsedArgs.passthrough.some(isDelegationFlag)) {
@@ -69,6 +69,7 @@ export async function runPlanOnHost(plan, target) {
         target,
     });
 }
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
 const PROBE_RESULT_PHRASES = {
     busy: 'is busy',
     free: 'is free',
@@ -133,6 +134,7 @@ async function delegate(options) {
     }
     const { host } = choice;
     const retained = { stderr: createBoundedBuffer(), stdout: createBoundedBuffer() };
+    const removeCheckoutsAfterMs = snapshot.ok ? await readRemoveCheckoutsAfterMs(env) : null;
     const result = snapshot.ok
         ? await runRemotely({
             command,
@@ -142,6 +144,7 @@ async function delegate(options) {
             monorepoRoot: context.monorepoRoot,
             nmrArgs: composeForwardedArgs(command, parsedArgs),
             remoteEnv,
+            removeCheckoutsAfterMs,
             snapshot,
             stderr: createTee(stderr, retained.stderr),
             stdout: createTee(stdout, retained.stdout),
@@ -178,6 +181,10 @@ async function delegate(options) {
 function formatRunHereLine(command, listedHosts, reason) {
     return `nmr: running ${command} here rather than on ${listedHosts}: ${reason}\n`;
 }
+async function readRemoveCheckoutsAfterMs(env) {
+    const days = (await loadUserConfig(env))?.config.delegate?.removeCheckoutsAfterDays ?? DEFAULT_REMOVE_CHECKOUTS_AFTER_DAYS;
+    return days === false ? null : days * MS_PER_DAY;
+}
 async function resolveHost(hosts, toplevel, env, stderr) {
     const [first, ...rest] = hosts;
     if (rest.length === 0) {

package/dist/esm/delegation/host-filesystem.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Appends to a failed step's message the resource that the host's filesystem has run out of, when the step's output
+ * reports a full filesystem and the counts that `runOnHost` reads say which. A write fails alike for lack of space and
+ * of inodes.
+ */
+export declare function appendFilesystemReason(message: string, output: string, runOnHost: (script: string) => Promise<{
+    exitCode: number;
+    output: string;
+}>): Promise<string>;
+/** Composes the shell command that prints, on the host, the free counts of the filesystem that holds its home. */
+export declare function composeFilesystemCheckScript(): string;
+/**
+ * Names the resource that the host's filesystem has run out of, from what `composeFilesystemCheckScript` printed, or
+ * returns `undefined` when neither is exhausted or the output does not include the counts. A filesystem that reports
+ * a total of zero inodes, as btrfs does, allocates them as it goes, so it cannot run out of them.
+ */
+export declare function describeExhaustedResource(output: string): string | undefined;
+/**
+ * Runs on the host and prints, as one JSON line, the total and free inodes and the blocks available to this user on
+ * the filesystem that holds the home directory. It is sent as source, so it refers to nothing outside its own body.
+ *
+ * @internal
+ */
+export declare function readHostFilesystem(): void;

package/dist/esm/delegation/host-filesystem.js

@@ -0,0 +1,45 @@
+import { quoteForShell } from "../helpers/quoteForShell.js";
+export async function appendFilesystemReason(message, output, runOnHost) {
+    if (!FULL_FILESYSTEM_PATTERN.test(output))
+        return message;
+    const check = await runOnHost(composeFilesystemCheckScript());
+    const reason = check.exitCode === 0 ? describeExhaustedResource(check.output) : undefined;
+    return reason === undefined ? message : `${message}: ${reason}`;
+}
+export function composeFilesystemCheckScript() {
+    return `node -e ${quoteForShell(`(${readHostFilesystem.toString()})();`)}`;
+}
+export function describeExhaustedResource(output) {
+    const counts = output
+        .split('\n')
+        .map(parseCounts)
+        .findLast((value) => value !== undefined);
+    if (counts !== undefined && counts.files > 0 && counts.ffree === 0)
+        return "the host's filesystem has run out of inodes";
+    if (counts?.bavail === 0)
+        return "the host's filesystem has run out of space";
+    return undefined;
+}
+export function readHostFilesystem() {
+    const fs = process.getBuiltinModule('node:fs');
+    const os = process.getBuiltinModule('node:os');
+    const { bavail, ffree, files } = fs.statfsSync(os.homedir());
+    process.stdout.write(`${JSON.stringify({ bavail, ffree, files })}\n`);
+}
+const FULL_FILESYSTEM_PATTERN = /no space left on device|ENOSPC/i;
+function parseCounts(line) {
+    try {
+        const value = JSON.parse(line);
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        if (!('bavail' in value) || !('ffree' in value) || !('files' in value))
+            return undefined;
+        const { bavail, ffree, files } = value;
+        return typeof bavail === 'number' && typeof ffree === 'number' && typeof files === 'number'
+            ? { bavail, ffree, files }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/delegation/remote-run.d.ts

@@ -1,5 +1,7 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** The directory on the host, relative to its home directory, that contains one directory per checkout key. */
+export declare const CHECKOUTS_DIR = ".cache/nmr/delegate";
 /** Names the hosts to which nmr delegates a command when the invocation does not say otherwise. */
 export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
 /** The flag that runs the command on a host that `NMR_DELEGATE` or the user config names. */
@@ -56,9 +58,11 @@ export declare function composeGitSshCommand(env: NodeJS.ProcessEnv): string;
  * @internal
  */
 export declare function composeSshArgv(env: NodeJS.ProcessEnv, host: string, remoteCommand: string): string[];
+/** Returns the key of the checkout on the host that serves the worktree at `toplevel` on the machine `hostname`. */
+export declare function deriveCheckoutKey(hostname: string, toplevel: string): string;
 /**
- * Returns the checkout's path on the host, relative to its home directory: a key derived from this machine and the
- * repository, followed by the repository's own directory name, which nmr on the host reports as the root's scope.
+ * Returns the checkout's path on the host, relative to its home directory: the checkout's key, followed by the
+ * repository's own directory name, which nmr on the host reports as the root's scope.
  *
  * @internal
  */
@@ -74,11 +78,12 @@ export declare function readLastLine(output: string): string;
  * Runs an nmr invocation on `host` against a snapshot of the local working tree, streaming the command's output to
  * `stdout` and `stderr` and returning its exit status.
  *
- * The host keeps one checkout per local repository and host name, under `~/.cache/nmr/delegate/`, so concurrent
+ * The host keeps one checkout per worktree on each delegating machine, under `~/.cache/nmr/delegate/`, so concurrent
  * delegations from different worktrees do not share a checkout, and `node_modules` and build output persist
- * between runs. Check out, install, and run take one connection, whose session holds the checkout's lock, so that two
- * delegations from one worktree run one after the other; what a phase other than `run` prints is returned rather than
- * streamed, because it matters only when the phase fails.
+ * between runs. Before the push, the delegation removes the host's other checkouts that have not been used for
+ * longer than `removeCheckoutsAfterMs`, unless it is `null`. Check out, install, and run take one connection, whose
+ * session holds the checkout's lock, so that two delegations from one worktree run one after the other; what a phase
+ * other than `run` prints is returned rather than streamed, because it matters only when the phase fails.
  */
 export declare function runRemotely(options: {
     command: string;
@@ -88,6 +93,7 @@ export declare function runRemotely(options: {
     monorepoRoot: string;
     nmrArgs: readonly string[];
     remoteEnv: Readonly<Record<string, string>>;
+    removeCheckoutsAfterMs: number | null;
     snapshot: {
         sha: string;
         toplevel: string;

package/dist/esm/delegation/remote-run.js

@@ -9,8 +9,11 @@ import { createBoundedBuffer } from "../helpers/createBoundedBuffer.js";
 import { quoteForShell } from "../helpers/quoteForShell.js";
 import { STALE_AFTER_MS } from "../machine-lock.js";
 import { formatFlagSpelling } from "../nmr-flags.js";
+import { appendFilesystemReason } from "./host-filesystem.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { composeSessionScript, createSessionDemultiplexer, formatDelegationWaitingLine } from "./remote-session.js";
+import { CHECKOUT_STAMP_PATH, composeCheckoutRemovalScript } from "./removeStaleCheckouts.js";
+export const CHECKOUTS_DIR = '.cache/nmr/delegate';
 export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
 export const DELEGATE_FLAG = formatFlagSpelling('delegate');
 export const DELEGATE_TO_FLAG = formatFlagSpelling('delegateTo');
@@ -28,9 +31,11 @@ export function composeSshArgv(env, host, remoteCommand) {
         ? ['ssh', ...sshArgs]
         : ['/bin/sh', '-c', `${sshCommand} "$@"`, sshCommand, ...sshArgs];
 }
+export function deriveCheckoutKey(hostname, toplevel) {
+    return createHash('sha256').update(`${hostname}\0${toplevel}`).digest('hex').slice(0, 16);
+}
 export function deriveCheckoutPath(hostname, toplevel) {
-    const key = createHash('sha256').update(`${hostname}\0${toplevel}`).digest('hex').slice(0, 16);
-    return path.posix.join('.cache/nmr/delegate', key, path.basename(toplevel));
+    return path.posix.join(CHECKOUTS_DIR, deriveCheckoutKey(hostname, toplevel), path.basename(toplevel));
 }
 export function formatMisplacedDelegationWarning(command, style) {
     return (`${STATUS_GLYPHS[style].warning.text} ${DELEGATE_FLAG}, ${DELEGATE_TO_FLAG}, and ${NO_DELEGATE_FLAG} after the ` +
@@ -44,15 +49,30 @@ export function readLastLine(output) {
         .findLast((line) => line !== '') ?? '');
 }
 export async function runRemotely(options) {
-    const { command, cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, snapshot, stderr, stdout } = options;
+    const { command, cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, removeCheckoutsAfterMs, snapshot, stderr, stdout, } = options;
     const checkoutPath = deriveCheckoutPath(os.hostname(), snapshot.toplevel);
     const checkoutDir = `"$HOME"/${quoteForShell(checkoutPath)}`;
-    const prepare = await runSsh(host, `mkdir -p ${checkoutDir} && cd ${checkoutDir} && { [ -d .git ] || git init --quiet; }`, env);
+    function runOnHost(script) {
+        return runSsh(host, script, env);
+    }
+    const removal = composeCheckoutRemovalScript({
+        checkoutsDir: CHECKOUTS_DIR,
+        lockPath: CHECKOUT_LOCK_PATH,
+        ownKey: deriveCheckoutKey(os.hostname(), snapshot.toplevel),
+        removeAfterMs: removeCheckoutsAfterMs,
+        staleAfterMs: STALE_AFTER_MS,
+        stampPath: CHECKOUT_STAMP_PATH,
+    });
+    const prepare = await runSsh(host, `{ ${removal} || :; }; mkdir -p ${checkoutDir} && cd ${checkoutDir} && { [ -d .git ] || git init --quiet; } && ` +
+        `{ touch ${quoteForShell(CHECKOUT_STAMP_PATH)} || :; }`, env);
     if (prepare.exitCode !== 0) {
+        const isUnreachable = prepare.exitCode === DELEGATION_FAILURE_EXIT_CODE;
         return {
             ok: false,
-            isUnreachable: prepare.exitCode === DELEGATION_FAILURE_EXIT_CODE,
-            message: `could not prepare ${host}`,
+            isUnreachable,
+            message: isUnreachable
+                ? `could not prepare ${host}`
+                : await appendFilesystemReason(`could not prepare ${host}`, prepare.output, runOnHost),
             output: prepare.output,
             phase: 'prepare',
             waitedMs: 0,
@@ -69,7 +89,8 @@ export async function runRemotely(options) {
         `${snapshot.sha}:${SNAPSHOT_REF}`,
     ], { cwd: snapshot.toplevel, env: { ...env, [SSH_COMMAND_ENV_VAR]: composeGitSshCommand(env) } });
     if (push.exitCode !== 0) {
-        return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push', waitedMs: 0 };
+        const message = await appendFilesystemReason(`could not push to ${host}`, push.output, runOnHost);
+        return { ok: false, message, output: push.output, phase: 'push', waitedMs: 0 };
     }
     const nonce = randomUUID();
     const marker = `__NMR_DELEGATE_${nonce}__`;
@@ -127,7 +148,8 @@ export async function runRemotely(options) {
     demultiplexer.flush();
     if (failure !== undefined) {
         const output = [demultiplexer.readOutput(), failure.output].filter((text) => text !== '').join('\n');
-        return { ok: false, message: describeFailedPhase(failure, host), output, phase: failure.phase, waitedMs };
+        const message = await appendFilesystemReason(describeFailedPhase(failure, host), output, runOnHost);
+        return { ok: false, message, output, phase: failure.phase, waitedMs };
     }
     if (!demultiplexer.hasStarted()) {
         return {

package/dist/esm/delegation/removeStaleCheckouts.d.ts

@@ -0,0 +1,33 @@
+/** The file whose mtime records a checkout's last use, relative to the checkout. */
+export declare const CHECKOUT_STAMP_PATH = ".git/nmr-delegate-used";
+/** What the removal needs, sent to it as JSON. */
+export interface CheckoutRemovalParams {
+    /** The directory that contains one directory per checkout key, relative to the host's home directory. */
+    checkoutsDir: string;
+    /** The checkout's lock file, relative to the checkout. */
+    lockPath: string;
+    /** The key of the delegation's own checkout, which is never removed. */
+    ownKey: string;
+    /** Age past which an unused checkout is removed, or `null` to keep every checkout. */
+    removeAfterMs: number | null;
+    /** Age at which an unrefreshed lock file is abandoned. */
+    staleAfterMs: number;
+    /** The file whose mtime records the checkout's last use, relative to the checkout. */
+    stampPath: string;
+}
+/** Composes the shell command that runs `removeStaleCheckouts` on the host. */
+export declare function composeCheckoutRemovalScript(params: CheckoutRemovalParams): string;
+/**
+ * Runs on the host and removes every checkout other than the delegation's own that has not been used for longer than
+ * `removeAfterMs` and whose lock does not have a live holder. A checkout's last use is the newest mtime of its stamp,
+ * `.git/index`, and `.git/HEAD`, so that a checkout made by an nmr that does not write the stamp still has one.
+ *
+ * Each checkout is renamed at once to a `.removing-` sibling, which needs no new inode, so that removal works on a
+ * filesystem without any free inodes and a delegation that starts later creates a fresh checkout. A detached `rm`
+ * then deletes every `.removing-` sibling, including those that an interrupted removal left, so that the delegation
+ * does not wait for it. An entry that cannot be read or moved is skipped. It is sent as source, so it refers to
+ * nothing outside its own body.
+ *
+ * @internal
+ */
+export declare function removeStaleCheckouts(params: CheckoutRemovalParams): void;

package/dist/esm/delegation/removeStaleCheckouts.js

@@ -0,0 +1,98 @@
+import { quoteForShell } from "../helpers/quoteForShell.js";
+export const CHECKOUT_STAMP_PATH = '.git/nmr-delegate-used';
+export function composeCheckoutRemovalScript(params) {
+    const source = `(${removeStaleCheckouts.toString()})(JSON.parse(process.argv[1]));`;
+    return `node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`;
+}
+export function removeStaleCheckouts(params) {
+    const fs = process.getBuiltinModule('node:fs');
+    const childProcess = process.getBuiltinModule('node:child_process');
+    const crypto = process.getBuiltinModule('node:crypto');
+    const os = process.getBuiltinModule('node:os');
+    const path = process.getBuiltinModule('node:path');
+    const removeAfterMs = params.removeAfterMs;
+    if (removeAfterMs === null)
+        return;
+    const rootDir = path.join(os.homedir(), params.checkoutsDir);
+    const REMOVING_PREFIX = '.removing-';
+    const now = Date.now();
+    for (const key of readNames(rootDir)) {
+        if (key.startsWith('.') || key === params.ownKey)
+            continue;
+        const keyDir = path.join(rootDir, key);
+        const checkouts = readNames(keyDir);
+        if (checkouts.length !== 1)
+            continue;
+        const checkoutDir = path.join(keyDir, checkouts[0] ?? '');
+        const lastUsedMs = readLastUsedMs(checkoutDir);
+        if (lastUsedMs === undefined || now - lastUsedMs <= removeAfterMs)
+            continue;
+        if (isLockHeld(path.join(checkoutDir, params.lockPath)))
+            continue;
+        try {
+            fs.renameSync(keyDir, path.join(rootDir, `${REMOVING_PREFIX}${crypto.randomUUID()}`));
+        }
+        catch {
+        }
+    }
+    const moved = readNames(rootDir)
+        .filter((name) => name.startsWith(REMOVING_PREFIX))
+        .map((name) => path.join(rootDir, name));
+    if (moved.length > 0) {
+        childProcess.spawn('rm', ['-rf', ...moved], { detached: true, stdio: 'ignore' }).unref();
+    }
+    function isLockHeld(lockPath) {
+        let content;
+        let mtimeMs;
+        try {
+            content = fs.readFileSync(lockPath, 'utf8');
+            ({ mtimeMs } = fs.statSync(lockPath));
+        }
+        catch {
+            return false;
+        }
+        if (Date.now() - mtimeMs > params.staleAfterMs)
+            return false;
+        const pid = readHolderPid(content);
+        return pid === undefined || !isProcessGone(pid);
+    }
+    function isProcessGone(pid) {
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH';
+        }
+    }
+    function readHolderPid(content) {
+        try {
+            const value = JSON.parse(content);
+            if (typeof value !== 'object' || value === null || !('pid' in value))
+                return undefined;
+            return typeof value.pid === 'number' ? value.pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function readLastUsedMs(checkoutDir) {
+        let newestMs;
+        for (const file of [params.stampPath, '.git/index', '.git/HEAD']) {
+            try {
+                newestMs = Math.max(newestMs ?? 0, fs.statSync(path.join(checkoutDir, file)).mtimeMs);
+            }
+            catch {
+            }
+        }
+        return newestMs;
+    }
+    function readNames(dir) {
+        try {
+            return fs.readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/esm/delegation/user-config.d.ts

@@ -2,6 +2,8 @@ import type { HostList } from './remote-run.js';
 /** The values that `delegate.when` accepts, each naming the runs that delegate without being asked. */
 declare const DELEGATE_WHEN_VALUES: readonly ["agent", "always"];
 export type DelegateWhen = (typeof DELEGATE_WHEN_VALUES)[number];
+/** The age, in days, past which a delegation removes a host's unused checkouts when the user config does not set one. */
+export declare const DEFAULT_REMOVE_CHECKOUTS_AFTER_DAYS = 7;
 /**
  * Renders a path for a message, with `~` standing for the home directory that `env` names when the path lies under
  * it.
@@ -30,6 +32,8 @@ export interface UserConfig {
 /** This machine's delegation hosts, and which runs delegate to them without being asked. */
 export interface UserDelegateConfig {
     hosts: HostList;
+    /** The age, in days, past which a delegation removes the host's unused checkouts; `false` keeps them. */
+    removeCheckoutsAfterDays?: number | false;
     when?: DelegateWhen;
 }
 export {};

package/dist/esm/delegation/user-config.js

@@ -5,6 +5,7 @@ import { assertRecognizedKeys } from "../config-validation.js";
 import { importConfigDefault } from "../helpers/importConfigDefault.js";
 import { resolveXdgBaseDir } from "../helpers/resolveXdgBaseDir.js";
 const DELEGATE_WHEN_VALUES = ['agent', 'always'];
+export const DEFAULT_REMOVE_CHECKOUTS_AFTER_DAYS = 7;
 export function formatDisplayPath(filePath, env) {
     const home = env['HOME'];
     if (home === undefined || !path.isAbsolute(home)) {
@@ -30,7 +31,7 @@ export function resolveUserConfigPath(env) {
 }
 const USER_CONFIG_RELATIVE_PATH = path.join('nmr', 'config.ts');
 const RECOGNIZED_KEYS = ['delegate'];
-const RECOGNIZED_DELEGATE_KEYS = ['hosts', 'when'];
+const RECOGNIZED_DELEGATE_KEYS = ['hosts', 'removeCheckoutsAfterDays', 'when'];
 function isDelegateWhen(value) {
     const values = DELEGATE_WHEN_VALUES;
     return values.includes(value);
@@ -45,16 +46,18 @@ function validateDelegateField(value, configPath) {
     }
     assertRecognizedKeys(delegate, RECOGNIZED_DELEGATE_KEYS, configPath, 'delegate.');
     const hosts = validateHosts(delegate['hosts'], configPath);
+    const removeCheckoutsAfterDays = validateRemoveCheckoutsAfterDays(delegate['removeCheckoutsAfterDays'], configPath);
+    const removal = removeCheckoutsAfterDays === undefined ? {} : { removeCheckoutsAfterDays };
     const when = delegate['when'];
     if (when === undefined) {
-        return { hosts };
+        return { hosts, ...removal };
     }
     if (!isDelegateWhen(when)) {
         const renderedValue = typeof when === 'string' ? when : JSON.stringify(when);
         throw new UserError(`Invalid nmr config at ${configPath}: \`delegate.when\` is \`${renderedValue}\`, which is not one of: ` +
             DELEGATE_WHEN_VALUES.join(', '));
     }
-    return { hosts, when };
+    return { hosts, ...removal, when };
 }
 function validateHosts(value, configPath) {
     const names = Array.isArray(value) && value.every((host) => typeof host === 'string')
@@ -67,6 +70,13 @@ function validateHosts(value, configPath) {
     }
     return [first, ...rest];
 }
+function validateRemoveCheckoutsAfterDays(value, configPath) {
+    if (value === undefined || value === false || (typeof value === 'number' && Number.isFinite(value) && value > 0)) {
+        return value;
+    }
+    throw new UserError(`Invalid nmr config at ${configPath}: \`delegate.removeCheckoutsAfterDays\` must be a positive number of days, ` +
+        'or `false` to keep every checkout');
+}
 function validateUserConfig(value, configPath) {
     if (!isRecord(value)) {
         throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);

package/docs/delegate.md

@@ -12,18 +12,19 @@ A machine that runs several worktrees' checks at once runs out of memory, and th
 
 ## The user config
 
-`~/.config/nmr/config.ts`, or `$XDG_CONFIG_HOME/nmr/config.ts` when `XDG_CONFIG_HOME` is set, declares this machine's hosts and when to delegate to them without being asked. It honors one key, `delegate`:
+`~/.config/nmr/config.ts`, or `$XDG_CONFIG_HOME/nmr/config.ts` when `XDG_CONFIG_HOME` is set, declares this machine's hosts, when to delegate to them without being asked, and how long a host keeps an unused checkout. It honors one key, `delegate`:
 
 ```ts
 export default {
-  delegate: { hosts: ['imac2', 'imac3'], when: 'agent' },
+  delegate: { hosts: ['imac2', 'imac3'], removeCheckoutsAfterDays: 14, when: 'agent' },
 };
 ```
 
 - **`hosts`** lists the hosts in order of preference. It is required whenever `delegate` is present.
+- **`removeCheckoutsAfterDays`** sets how long a checkout on a host may go unused before a delegation from this machine removes it, in days; `false` keeps every checkout. It defaults to 7. See [unused checkouts](#unused-checkouts).
 - **`when`** turns on delegation by default: `'agent'` for every run whose environment contains an agent-harness marker, the variables that also select [quiet output](reporting.md#configuring), extended by the repo's `output.extraAgentEnvVars`; `'always'` for every run. Without `when`, nmr delegates only on request, and `hosts` serves `--delegate`.
 
-nmr reads the file only when a decision reaches it, and an unrecognized key, a malformed `hosts`, or an unknown `when` fails that run with an error naming the file and the key. The file cannot import anything from a repo, so it is a plain object rather than a `defineConfig` call. When a directory above it contains a `package.json` without `"type"`, such as a stray `~/package.json`, Node warns on every load that the file's module type is not specified; a `~/.config/nmr/package.json` containing `{ "type": "module" }` silences it.
+nmr reads the file when a run reaches rule 7 of [choosing where a command runs](#choosing-where-a-command-runs), and for every delegation, however it was requested, to learn `removeCheckoutsAfterDays`; a run that an earlier rule keeps here does not read it. An unrecognized key, a malformed `hosts`, or an unknown `when` fails that run with an error naming the file and the key. The file cannot import anything from a repo, so it is a plain object rather than a `defineConfig` call. When a directory above it contains a `package.json` without `"type"`, such as a stray `~/package.json`, Node warns on every load that the file's module type is not specified; a `~/.config/nmr/package.json` containing `{ "type": "module" }` silences it.
 
 A pass that a host earns satisfies a later delegation to that host, but not a run here: Under `when`, a run that `--no-delegate` keeps here re-runs a check that the host already passed. See [consulting the cache first](#consulting-the-cache-first).
 
@@ -100,11 +101,21 @@ $ nmr --delegate-to imac2 ci
 
 nmr records the working tree as it is on disk as a commit: tracked changes, staged or not, and untracked files that git does not ignore. This is the tree that a local run checks. The commit is built in a temporary index, so the repository's index, refs, and stash do not change.
 
-nmr pushes the commit to a checkout on the host under `~/.cache/nmr/delegate/`, without running the repository's `pre-push` hook, then runs `pnpm install --frozen-lockfile` and the command from the directory that corresponds to the local one, with nmr's own flags as they were given. The host keeps one checkout for each repository on each machine that delegates to it, so concurrent delegations from different worktrees do not share one, and `node_modules` and build output persist between runs. When the workspace packages' `bin` entries differ from those of the checkout's last successful install, nmr first removes pnpm's workspace state, so that the install links the new bins, which an unchanged lockfile would otherwise let pnpm skip; that install reruns the workspace's `prepare` scripts. nmr does not remove these checkouts.
+nmr pushes the commit to a checkout on the host under `~/.cache/nmr/delegate/`, without running the repository's `pre-push` hook, then runs `pnpm install --frozen-lockfile` and the command from the directory that corresponds to the local one, with nmr's own flags as they were given. The host keeps one checkout for each worktree on each machine that delegates to it, so concurrent delegations from different worktrees do not share one, and `node_modules` and build output persist between runs. When the workspace packages' `bin` entries differ from those of the checkout's last successful install, nmr first removes pnpm's workspace state, so that the install links the new bins, which an unchanged lockfile would otherwise let pnpm skip; that install reruns the workspace's `prepare` scripts.
 
 - **Ignored files stay here.** A command that needs a gitignored file, such as a local `.env`, does not find it on the host.
 - **A repository with submodules cannot be delegated**, nor can a tree containing a nested repository, because the snapshot does not include their content. A delegation flag refuses such a tree; under `NMR_DELEGATE` or the user config, the command runs here, and nmr prints one line saying why.
 
+### Unused checkouts
+
+A worktree adds a checkout on each host to which it delegates, with its own `node_modules`, so the checkouts accumulate as worktrees come and go. Before it pushes, each delegation removes the host's other checkouts that have not been used for longer than the delegating machine's `removeCheckoutsAfterDays`, whichever machine created them:
+
+- **A checkout's last use** is the last delegation to it. A checkout made by an nmr that does not record its use is dated by its last check out.
+- **A checkout in use is kept**: one whose lock, described below, has a live holder, whatever its age. The delegation's own checkout is never removed.
+- **The delegation does not wait for the deletion.** It moves each checkout aside at once and deletes it in the background, so a delegation that starts later creates a fresh checkout and installs it from scratch.
+- **The removal runs before the push**, so a host whose filesystem the checkouts have filled recovers without anyone deleting files by hand: The delegation that removes the checkouts may still fail, and the next one finds the room. Removal never fails a delegation.
+- **Each machine applies its own age.** A machine whose user config says `false` removes nothing, while another machine delegating to the same host still removes the checkouts that are older than its own age.
+
 Delegations from the same worktree share its checkout on the host, so they run one at a time. A delegation that starts while another holds the checkout waits for it, saying so on stderr, then runs:
 
 ```console
@@ -128,7 +139,13 @@ A failure of the delegation itself, rather than of the command, exits 255, the s
 ❌ my-repo: ci: failed on 📡 imac2 in 10.0s (exit 255) — could not prepare imac2
 ```
 
-The steps are `prepare`, which reaches the host and creates the checkout, `push`, `check out`, and `install`. A connection lost while the command runs is reported as `lost connection to <host>`.
+The steps are `prepare`, which reaches the host, removes its [unused checkouts](#unused-checkouts), and creates the checkout, `push`, `check out`, and `install`. A connection lost while the command runs is reported as `lost connection to <host>`.
+
+A step that fails with `No space left on device` reports which resource the host's filesystem has run out of, because a write fails the same way for both:
+
+```console
+❌ my-repo: ci: failed on 📡 imac2 in 3.1s (exit 255) — could not push to imac2: the host's filesystem has run out of inodes
+```
 
 ### When no host answers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -84,7 +84,7 @@
     "@williamthorsen/toolbelt.errors": "0.10.0",
     "@williamthorsen/toolbelt.filesystem": "0.10.2",
     "glob": "14.0.4",
-    "prettier": "3.9.10",
+    "prettier": "3.10.0",
     "prettier-plugin-sh": "0.20.2",
     "taze": "21.3.0",
     "unconfig": "7.5.0"