@williamthorsen/nmr 2.0.3 → 2.2.0

package/dist/esm/check-cache/check-cache-entries.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { isRecord, readCacheEntry, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { isStringRecord } from "../helpers/type-guards.js";
+import { isStringRecord } from "../helpers/isStringRecord.js";
 import { writeDebugNote } from "./check-cache.js";
 const CACHE_TOOL = 'nmr-check';
 const UNSAFE_SLUG_CHARACTERS = /[^\w.-]+/g;

package/dist/esm/check-cache/check-cache-gate.js

@@ -7,11 +7,11 @@ import { resolveChannel } from "../output-channel.js";
 import { splitSegments } from "../shell-syntax.js";
 import { formatMisplacedNoCacheWarning, isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
-import { recordDelegatedPass } from "./check-cache-delegation.js";
 import { certifyRetention, readCheckCacheEntry } from "./check-cache-entries.js";
 import { computeCacheKey, computeRetentionKey } from "./check-cache-key.js";
 import { recordPass } from "./check-cache-record.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
+import { recordDelegatedPass } from "./recordDelegatedPass.js";
 export function openGate(options) {
     const { command, config, env, monorepoRoot, passthrough, readTree, stderr, style } = options;
     if (!isCacheableCommand(config.checkCache, command)) {

package/dist/esm/check-cache/check-cache-record.js

@@ -4,13 +4,13 @@ import { isEnvSwitchOn } from "../env-switch.js";
 import { deriveExcerpt } from "../helpers/deriveExcerpt.js";
 import { composeTranscript } from "../helpers/transcript.js";
 import { RUN_IF_PRESENT_ENV_VAR, VERSION } from "../invocation.js";
+import { assembleReplay } from "./assembleReplay.js";
 import { isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { readCheckCacheEntry, recordTranscript, writeCheckCacheEntry, } from "./check-cache-entries.js";
 import { CURRENT_RUNTIME } from "./check-cache-key.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
-import { assembleReplay } from "./replay-assembly.js";
 export async function recordHostPass(options) {
     const { env, host, key, ref, retention, snapshot, stderr } = options;
     const recorded = await readCheckCacheEntry(ref);

package/dist/esm/check-cache/check-cache.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { hashWorkingTree, readHeadSha, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { isEnvSwitchOn } from "../env-switch.js";
-import { isHookName } from "../helpers/hook-name.js";
+import { isHookName } from "../helpers/isHookName.js";
 export const GIT_TREE_READER = { hashWorkingTree, readHeadSha };
 export const DEBUG_ENV_VAR = 'NMR_DEBUG';
 export const DEFAULT_CACHEABLE_COMMANDS = [

package/dist/esm/commands/build.js

@@ -8,8 +8,8 @@ import { writeStatedOutcome } from "../stated-outcome.js";
 import { DEFAULT_OUTDIR, hasExpectedBuildOutput, readEmitDuration, resolveBuildCachePath, resolveEntryPoints, resolveToolchainFingerprint, writeEmitDuration, } from "./build-output.js";
 import { assertSupportedTypeScript, formatDiagnostics, getCompiler, loadCompiler } from "./compiler.js";
 import { discardScratchDirs, publishOutput, removeScratchDirs } from "./publish-output.js";
+import { resolveTsconfigChain } from "./resolveTsconfigChain.js";
 import { rewriteSpecifiers } from "./rewrite-specifiers.js";
-import { resolveTsconfigChain } from "./tsconfig-chain.js";
 const SOURCE_ROOT = 'src';
 export async function buildPackage(packageDir, options = {}) {
     await loadCompiler(options.loadTypeScript);

package/dist/esm/commands/fmt.js

@@ -10,8 +10,8 @@ import { NMR_FMT_BIN } from "../bins.js";
 import { NO_CACHE_ENV_VAR } from "../check-cache/check-cache.js";
 import { readEnvSwitch } from "../env-switch.js";
 import { prepareFmtCache } from "./fmt-cache.js";
-import { resolveFormatTargets } from "./format-targets.js";
 import { BROKEN_MANIFEST_FIX, findPackageManifest, resolveDeclaredCli, } from "./package-manifest.js";
+import { resolveFormatTargets } from "./resolveFormatTargets.js";
 import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default.config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));

package/dist/esm/commands/taze.js

@@ -4,11 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_TAZE_BIN } from "../bins.js";
-import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
+import { loadPackageMaturityPeriod } from "./loadPackageMaturityPeriod.js";
 import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
+import { planTazePasses } from "./planTazePasses.js";
 import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { isSilent, readFlag } from "./taze-args.js";
-import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 const REQUEST_TIMEOUT_FLAG = '--request-timeout';
 const REQUEST_TIMEOUT_FLAGS = [REQUEST_TIMEOUT_FLAG, '--requestTimeout'];

package/dist/esm/config-validation.js

@@ -1,11 +1,11 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
-import { assertResolvableCheckCacheCommands } from "./check-cache/config-check-cache.js";
+import { assertResolvableCommandLists } from "./assertResolvableCommandLists.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'delegate', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'delegate', 'fanOut', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -17,6 +17,7 @@ export const CONFIG_TIERS = {
 const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.workspace.honoredKeys];
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
+const RECOGNIZED_FAN_OUT_KEYS = ['extraSortedCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_SELF_HOSTED_RUNNER_KEYS = ['exempt'];
 const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments', 'shouldRunInBackground'];
@@ -43,6 +44,9 @@ export function validateConfig(value, configPath, baseDir) {
         config.checkCache = checkCache;
     if (value['delegate'] !== undefined)
         config.delegate = validateDelegateField(value['delegate'], configPath);
+    const fanOut = validateFanOutField(value, configPath);
+    if (fanOut)
+        config.fanOut = fanOut;
     const output = validateOutputField(value, configPath);
     if (output)
         config.output = output;
@@ -55,7 +59,7 @@ export function validateConfig(value, configPath, baseDir) {
     const selfHostedRunner = validateSelfHostedRunnerField(value, configPath);
     if (selfHostedRunner)
         config.selfHostedRunner = selfHostedRunner;
-    assertResolvableCheckCacheCommands(config, configPath, baseDir);
+    assertResolvableCommandLists(config, configPath, baseDir);
     return config;
 }
 function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
@@ -166,6 +170,24 @@ function validateDelegateField(delegate, configPath) {
     throw new UserError(`Invalid nmr config at ${configPath}: \`delegate\` accepts only \`false\`, which keeps the repo's checks on the ` +
         'machine that has the tree. Hosts and `when` belong in the user config, `~/.config/nmr/config.ts`.');
 }
+function validateFanOutField(value, configPath) {
+    const fanOut = value['fanOut'];
+    if (fanOut === undefined) {
+        return undefined;
+    }
+    if (!isRecord(fanOut)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`fanOut\` must be an object`);
+    }
+    assertRecognizedKeys(fanOut, RECOGNIZED_FAN_OUT_KEYS, configPath, 'fanOut.');
+    const extraSortedCommands = fanOut['extraSortedCommands'];
+    if (extraSortedCommands === undefined) {
+        return {};
+    }
+    if (!isStringArray(extraSortedCommands)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`fanOut.extraSortedCommands\` must be a string[]`);
+    }
+    return { extraSortedCommands };
+}
 function validateOutputField(value, configPath) {
     const output = value['output'];
     if (output === undefined) {

package/dist/esm/config.js

@@ -3,8 +3,8 @@ import { UserError } from '@williamthorsen/nmr-core';
 import { CONFIG_TIERS, validateConfig } from "./config-validation.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
-import { isHookName } from "./helpers/hook-name.js";
 import { importConfigDefault } from "./helpers/importConfigDefault.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { describeScript } from "./resolver.js";
 import { readSelfReference, readStepListSelfReference } from "./steps.js";

package/dist/esm/crossing-diagnostics.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { STATUS_GLYPHS, UserError } from '@williamthorsen/nmr-core';
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { hasRunnableHook } from "./hooks.js";
 import { expandScript, findChainedSelfReference, readPackageJsonScripts, } from "./resolver.js";

package/dist/esm/defineConfig.d.ts

@@ -1,5 +1,5 @@
 import type { NmrConfig } from './types.js';
-export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, SelfHostedRunnerConfig, StepSpec, } from './types.js';
+export type { BuildConfig, CheckCacheConfig, CommandVerbosity, FanOutConfig, NmrConfig, OutputConfig, ScriptValue, SelfHostedRunnerConfig, StepSpec, } from './types.js';
 /**
  * Returns `config` unchanged, typing a configuration file's default export as `NmrConfig`.
  *

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

@@ -9,11 +9,11 @@ import { createBoundedBuffer } from "../helpers/createBoundedBuffer.js";
 import { USAGE_EXIT_CODE, } from "../invocation.js";
 import { isDelegationFlag } from "../invocation-args.js";
 import { reportVerdict } from "../presentation.js";
-import { resolveDelegationTarget } from "./delegation-target.js";
+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 { createSnapshot } from "./remote-snapshot.js";
-import { formatDisplayPath, loadUserConfig } from "./user-config.js";
+import { resolveDelegationTarget } from "./resolveDelegationTarget.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-probe.js

@@ -2,8 +2,8 @@ import path from 'node:path';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { quoteForShell } from "../helpers/quoteForShell.js";
 import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "../machine-lock.js";
+import { probeHostLocks } from "./probeHostLocks.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
-import { probeHostLocks } from "./remote-probe-host.js";
 import { DELEGATION_FAILURE_EXIT_CODE, readLastLine, runSsh } from "./remote-run.js";
 export function chooseHost(options) {
     const { hosts, onSettled, probe } = options;

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

@@ -1,7 +1,9 @@
 import type { HostList } from './remote-run.js';
 /** The values that `delegate.when` accepts, each naming the runs that delegate without being asked. */
-export declare const DELEGATE_WHEN_VALUES: readonly ["agent", "always"];
+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,5 +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 {};