@williamthorsen/nmr 2.0.3 → 2.2.0

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

@@ -4,7 +4,8 @@ import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertRecognizedKeys } from "../config-validation.js";
 import { importConfigDefault } from "../helpers/importConfigDefault.js";
 import { resolveXdgBaseDir } from "../helpers/resolveXdgBaseDir.js";
-export const DELEGATE_WHEN_VALUES = ['agent', 'always'];
+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/dist/esm/{help.js → describeHelp.js}

@@ -1,5 +1,5 @@
 import { DELEGATE_ENV_VAR } from "./delegation/remote-run.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 const LIFECYCLE_SCRIPT_NAMES = new Set([

package/dist/esm/fan-out.d.ts

@@ -5,6 +5,7 @@ import { type RunCliResult } from './invocation.js';
 import type { ParsedArgs } from './nmr-flags.js';
 import type { RunSteps, RunStepsOptions } from './runner.js';
 import type { Step } from './steps.js';
+import type { NmrConfig } from './types.js';
 /**
  * Composes the delegation that an `-F` or `-R` calls for, or `undefined` when the invocation runs here.
  *
@@ -15,10 +16,16 @@ import type { Step } from './steps.js';
  *
  * A `--log` fan-out surveys the scopes selected, so a scope with nothing to show is a gap in the survey rather
  * than a failure of it, however that scope was selected.
+ *
+ * pnpm runs the selected packages in topological order unless told otherwise, which holds each package's run until
+ * its workspace dependencies have finished theirs. Only a command that reads what its dependencies' runs produce
+ * needs that, so the order is kept for `build` and for the commands in `fanOut.extraSortedCommands`, and every
+ * other fan-out runs with `--no-sort`.
  */
 export declare function composeDelegation(options: {
     childEnv: NodeJS.ProcessEnv;
     command: string;
+    config: NmrConfig;
     parsedArgs: ParsedArgs;
 }): {
     env: NodeJS.ProcessEnv;

package/dist/esm/fan-out.js

@@ -6,8 +6,9 @@ import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
 import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
 const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
+const DEFAULT_SORTED_COMMANDS = new Set(['build']);
 export function composeDelegation(options) {
-    const { childEnv, command, parsedArgs } = options;
+    const { childEnv, command, config, parsedArgs } = options;
     let scope;
     let shouldRunIfPresent = parsedArgs.shouldPrintLog;
     if (parsedArgs.filter) {
@@ -20,12 +21,13 @@ export function composeDelegation(options) {
     if (scope === undefined) {
         return undefined;
     }
+    const sortFlags = isSortedCommand(command, config) ? [] : ['--no-sort'];
     const flags = parsedArgs.shouldPrintLog ? ['--log'] : [];
     return {
         env: shouldRunIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
         step: {
             kind: 'structural',
-            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
+            argv: ['pnpm', ...scope, ...sortFlags, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
         },
     };
 }
@@ -136,6 +138,9 @@ function formatEmptyFilterError(pattern, names) {
 function formatFilterRejection(pattern) {
     return `-F/--filter did not match any workspace: \`${pattern}\`.`;
 }
+function isSortedCommand(command, config) {
+    return DEFAULT_SORTED_COMMANDS.has(command) || (config.fanOut?.extraSortedCommands ?? []).includes(command);
+}
 function suggestWorkspaceNames(pattern, names) {
     if (names.length === 0) {
         return '';

package/dist/esm/invocation.d.ts

@@ -2,7 +2,7 @@ import type { Writable } from 'node:stream';
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 import type { TreeReader, TreeSnapshot } from './check-cache/check-cache.js';
 import type { ResolvedContext } from './context.js';
-import type { DelegationTarget } from './delegation/delegation-target.js';
+import type { DelegationTarget } from './delegation/resolveDelegationTarget.js';
 import type { ReadFilterSelection } from './helpers/filter-selection.js';
 import type { ParsedArgs } from './nmr-flags.js';
 import type { ReportFormat } from './report-format.js';

package/dist/esm/machine-lock.d.ts

@@ -1,7 +1,5 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-/** How often a holder refreshes the lock file's mtime. */
-export declare const HEARTBEAT_INTERVAL_MS = 10000;
 /**
  * The commands that take the machine lock: the ones whose memory peak makes two concurrent runs slower than two in
  * sequence. `test:watch` is absent because it runs until it is stopped, and holding the lock would block every other
@@ -16,8 +14,6 @@ export declare const LOCK_FILE = "heavy.lock";
 export declare const LOCK_TOKEN_ENV_VAR = "NMR_MACHINE_LOCK_TOKEN";
 /** Set to `1` to run without the lock, for the whole chain. */
 export declare const NO_LOCK_ENV_VAR = "NMR_NO_LOCK";
-/** How often a waiter checks the lock again. */
-export declare const POLL_INTERVAL_MS = 1000;
 /**
  * Age at which an unrefreshed lock file is abandoned. It covers a holder whose pid was reused by another process,
  * and a file left half-written, neither of which a liveness check detects.

package/dist/esm/machine-lock.js

@@ -8,7 +8,7 @@ import { isRecord, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { isEnvSwitchOn } from "./env-switch.js";
 const RECLAIM_GUARD = 'heavy.lock.reclaim';
 const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
-export const HEARTBEAT_INTERVAL_MS = 10_000;
+const HEARTBEAT_INTERVAL_MS = 10_000;
 export const HEAVY_COMMANDS = new Set([
     'check',
     'check:strict',
@@ -28,7 +28,7 @@ export const LOCK_DIR_ENV_VAR = 'NMR_LOCK_DIR';
 export const LOCK_FILE = 'heavy.lock';
 export const LOCK_TOKEN_ENV_VAR = 'NMR_MACHINE_LOCK_TOKEN';
 export const NO_LOCK_ENV_VAR = 'NMR_NO_LOCK';
-export const POLL_INTERVAL_MS = 1000;
+const POLL_INTERVAL_MS = 1000;
 export const STALE_AFTER_MS = 60_000;
 export async function acquireMachineLock(options) {
     const { command, dir, env, stderr } = options;

package/dist/esm/presentation.js

@@ -1,5 +1,5 @@
 import { describeInvalidOutputStyle } from '@williamthorsen/nmr-core';
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { resolveOutputStyles } from "./output-style.js";
 import { readReportFormatEnv } from "./report-format.js";
 import { readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";

package/dist/esm/report-format.d.ts

@@ -1,10 +1,3 @@
-/**
- * Renders the rejection of a value off the format ladder, naming where it was written. Every source that
- * accepts a format renders through this, so two of them can never come to name different ladders.
- */
-export declare function formatReportFormatRejection(source: string, value: string): string;
-/** Narrows a raw value to a point on the format ladder. */
-export declare function isReportFormat(value: string): value is ReportFormat;
 /**
  * Reads the format that the environment names. An unrecognized value is returned as an error, which keeps a
  * misspelling from going unnoticed for the life of the shell.
@@ -22,7 +15,7 @@ export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
  * The points on the format ladder. `text` is a named point, so that one invocation can override a format
  * exported for the shell in either direction.
  */
-export declare const REPORT_FORMATS: readonly ["text", "json"];
+declare const REPORT_FORMATS: readonly ["text", "json"];
 /** How nmr renders its own verdicts, which is never the output of the commands that it runs. */
 export type ReportFormat = (typeof REPORT_FORMATS)[number];
 /** The format that the environment names, if any, or the message naming why its value could not be read. */
@@ -44,3 +37,4 @@ export interface ResolveReportFormatOptions {
     envFormat: ReportFormat | undefined;
     hasJsonFlag: boolean;
 }
+export {};

package/dist/esm/report-format.js

@@ -1,10 +1,3 @@
-export function formatReportFormatRejection(source, value) {
-    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
-}
-export function isReportFormat(value) {
-    const names = REPORT_FORMATS;
-    return names.includes(value);
-}
 export function readReportFormatEnv(env) {
     const rawValue = env[REPORT_FORMAT_ENV_VAR];
     if (rawValue === undefined || rawValue === '') {
@@ -16,10 +9,17 @@ export function readReportFormatEnv(env) {
     return { ok: true, format: rawValue };
 }
 export const REPORT_FORMAT_ENV_VAR = 'NMR_REPORT_FORMAT';
-export const REPORT_FORMATS = ['text', 'json'];
+const REPORT_FORMATS = ['text', 'json'];
 export function resolveReportFormat(options) {
     const { envFormat, hasJsonFlag } = options;
     if (hasJsonFlag)
         return 'json';
     return envFormat ?? 'text';
 }
+function formatReportFormatRejection(source, value) {
+    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
+}
+function isReportFormat(value) {
+    const names = REPORT_FORMATS;
+    return names.includes(value);
+}

package/dist/esm/resolve-scripts.js

@@ -1,6 +1,6 @@
 import { buildRootScripts, workspaceScripts } from "./default-scripts.js";
+import { toWorkspacePackageGlobs } from "./toWorkspacePackageGlobs.js";
 import { resolveWorkspace } from "./workspace.js";
-import { toWorkspacePackageGlobs } from "./workspace-globs.js";
 export function getDefaultWorkspaceScripts() {
     return { ...workspaceScripts };
 }

package/dist/esm/route.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { createCli, UsageError } from '@williamthorsen/nmr-core/cli';
 import { DEBUG_ENV_VAR, NO_CACHE_ENV_VAR } from "./check-cache/check-cache.js";
+import { describeHelp } from "./describeHelp.js";
 import { readEnvSwitch, readEnvSwitches } from "./env-switch.js";
 import { listDefinedCommands } from "./fan-out.js";
-import { describeHelp } from "./help.js";
 import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
 import { NO_LOCK_ENV_VAR } from "./machine-lock.js";
 import { NMR_FLAGS, toParsedArgs } from "./nmr-flags.js";

package/dist/esm/run-chain.js

@@ -4,7 +4,7 @@ import { NMR_BIN } from "./bins.js";
 import { resolveCacheKey } from "./check-cache/check-cache-gate.js";
 import { reportNmrCrossing } from "./crossing-diagnostics.js";
 import { NMR_GLYPHS } from "./glyphs.js";
-import { isHookName } from "./helpers/hook-name.js";
+import { isHookName } from "./helpers/isHookName.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
 import { wrapWithHooks } from "./hooks.js";
 import { USAGE_EXIT_CODE } from "./invocation.js";

package/dist/esm/runCli.js

@@ -1,6 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { runCli as runRouter } from '@williamthorsen/nmr-core/cli';
-import { prependBinDirs } from "./bin-path.js";
 import { NMR_BIN } from "./bins.js";
 import { GIT_TREE_READER, NO_CACHE_ENV_VAR, resolveRunId, RUN_ID_ENV_VAR, } from "./check-cache/check-cache.js";
 import { openGate, runGated } from "./check-cache/check-cache-gate.js";
@@ -17,6 +16,7 @@ import { readFilterSelection as readFilterSelectionDefault, } from "./helpers/fi
 import { RUN_IF_PRESENT_ENV_VAR, USAGE_EXIT_CODE, VERSION, } from "./invocation.js";
 import { formatMisplacedFlagHint } from "./invocation-args.js";
 import { readInvocationFlags } from "./nmr-flags.js";
+import { prependBinDirs } from "./prependBinDirs.js";
 import { reportVerdict } from "./presentation.js";
 import { buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
 import { buildRoot, buildVersionRoot } from "./route.js";
@@ -104,7 +104,7 @@ async function planRun(invocation, target) {
         stderr,
         env: childEnv,
     };
-    const delegation = composeDelegation({ childEnv, command, parsedArgs });
+    const delegation = composeDelegation({ childEnv, command, config: context.config, parsedArgs });
     if (delegation !== undefined) {
         const lock = await takeMachineLock(invocation);
         let result;

package/dist/esm/tiers.js

@@ -1,6 +1,6 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
-import { listGitIgnoredPaths } from "./git-ignored-paths.js";
+import { listGitIgnoredPaths } from "./listGitIgnoredPaths.js";
 const TEST_DIR = '__tests__';
 const TEST_EXTENSIONS = '{ts,tsx}';
 const TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;

package/dist/esm/types.d.ts

@@ -28,6 +28,17 @@ export interface CheckCacheConfig {
      */
     extraCommands?: string[];
 }
+/** Fan-out settings honored at the monorepo root. */
+export interface FanOutConfig {
+    /**
+     * Command names added to the set whose `-R` and `-F` fan-outs run packages in topological order, which holds
+     * `build` by default; every other fan-out starts each package without waiting for its workspace dependencies.
+     * Extends rather than replaces, so that declaring one command cannot drop `build`. List a command whose run in a
+     * package reads what the same command produces in that package's workspace dependencies. Every name has to
+     * resolve to a command, because a misspelt entry would otherwise be inert.
+     */
+    extraSortedCommands?: string[];
+}
 /** Self-hosted runner settings honored at the monorepo root, read by nmr's readyup kit. */
 export interface SelfHostedRunnerConfig {
     /**
@@ -59,6 +70,7 @@ export interface NmrConfig {
      * config says. A delegation flag still sends a run elsewhere.
      */
     delegate?: false;
+    fanOut?: FanOutConfig;
     output?: OutputConfig;
     workspaceScripts?: Record<string, ScriptValue>;
     rootScripts?: Record<string, ScriptValue>;

package/dist/esm/verbosity.d.ts

@@ -9,7 +9,7 @@ export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROV
  * The points on the loudness ladder. Both are spelled out rather than leaving `full` implicit in the variable's
  * absence, so that a repo-level default is overridable from the environment in either direction.
  */
-export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
+declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
 /**
  * Passes the resolved verbosity down the chain of spawned processes, so that `-q` applies to every process rather
  * than only the first. The pass key does not include it: It changes what a run prints and never what a command
@@ -65,3 +65,4 @@ export type VerbosityRead = {
     ok: false;
     error: string;
 };
+export {};

package/dist/esm/verbosity.js

@@ -1,5 +1,5 @@
 export const AGENT_ENV_VARS = ['CLAUDECODE', 'ROVODEV_CLI', 'ROVO_CLI'];
-export const COMMAND_VERBOSITIES = ['full', 'quiet'];
+const COMMAND_VERBOSITIES = ['full', 'quiet'];
 export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
 export function formatVerbosityRejection(source, value) {
     return `${source} is \`${value}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`;

package/dist/esm/vitest.js

@@ -3,12 +3,12 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { defaultExclude, mergeConfig } from 'vitest/config';
-import { listGitIgnoredPaths } from "./git-ignored-paths.js";
+import { listGitIgnoredPaths } from "./listGitIgnoredPaths.js";
 import { ALL_TEST_PATTERNS, buildTierPatterns, TEST_COLLECTION_EXCLUDE, TIER_NAMES } from "./tiers.js";
+import { toWorkspacePackageGlobs } from "./toWorkspacePackageGlobs.js";
 import { deriveDefaultMaxWorkers, readMaxWorkersFlag } from "./vitest-max-workers.js";
 import { createSourceResolutionPlugin } from "./vitest-source-resolution.js";
 import { getWorkspacePackageDirs } from "./workspace.js";
-import { toWorkspacePackageGlobs } from "./workspace-globs.js";
 const [RESIDUAL_TIER, ...NAMED_TIERS] = TIER_NAMES;
 const TIERED_PATTERNS = NAMED_TIERS.flatMap(buildTierPatterns);
 const TIER_TIMEOUT_MS = 30_000;

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/docs/scripts.md

@@ -41,6 +41,17 @@ A script value is a string or an array of steps. Only the built-in defaults and
 
 Each array element is a command name, optionally preceded by nmr's own flags, split on whitespace: `-R test` runs the element in every package, the way `nmr -R test` does. An element containing a quoted argument or shell syntax is rejected when the config loads: Name that command as a script of its own and reference the name.
 
+#### Package order in a fan-out
+
+An `-R` or `-F` fan-out of `build` runs the packages in topological order, so that each package builds after its workspace dependencies. Every other fan-out passes `--no-sort` to pnpm and starts each package's command without waiting for its dependencies to finish theirs: `test`, the `test:*` commands, and `typecheck` read the `dist` that an earlier `build` wrote, not anything that the same command writes in another package. A command that does read what its dependencies' runs of it produce, such as a code generator whose output a dependent package imports, keeps the order once `fanOut.extraSortedCommands` lists it:
+
+```ts
+// .config/nmr.config.ts
+export default defineConfig({ fanOut: { extraSortedCommands: ['generate'] } });
+```
+
+The list adds to `build` and cannot remove it, and a name in it that does not resolve to any command fails when the config loads.
+
 #### Running a step in the background
 
 A composite runs its steps in series. An element declared with `shouldRunInBackground` starts and is left running while the steps after it run:
@@ -125,6 +136,7 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 | `delegate`         | `false`                                                                       | Keeps every check on the machine that has the tree, whatever `NMR_DELEGATE` or the [user config](delegate.md#the-user-config) says; a delegation flag still sends a run elsewhere (root config only)                                                                                                                                         |
 | `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                                                                                                                                                                                                                                                                               |
 | `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                                                                                                                                                                                                                                                                                    |
+| `fanOut`           | `{ extraSortedCommands?: string[] }`                                          | Commands whose fan-out runs packages in topological order, besides `build`; see [package order in a fan-out](#package-order-in-a-fan-out) (root config only)                                                                                                                                                                                 |
 | `output`           | `{ commandVerbosity?: CommandVerbosity; extraAgentEnvVars?: string[] }`       | How loudly runs report command output; see [configuring](reporting.md#configuring)                                                                                                                                                                                                                                                           |
 | `selfHostedRunner` | `{ exempt: string }`                                                          | Why a qualifying repo keeps CI off the self-hosted runners; stops [nmr's readyup kit](../README.md#conformance-checks) from recommending `CI_RUNS_ON` (root config only). The reason is structural: a circular dependency, a platform or capacity the runners lack, or network reach. A missing tool is installed by a workflow step instead |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -81,22 +81,22 @@
   ],
   "dependencies": {
     "@williamthorsen/nmr-core": "0.16.2",
-    "@williamthorsen/toolbelt.errors": "0.9.1",
-    "@williamthorsen/toolbelt.filesystem": "0.10.1",
+    "@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"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.8.1",
-    "@williamthorsen/toolbelt.vitest": "0.13.3",
+    "@williamthorsen/toolbelt.testing": "0.8.2",
+    "@williamthorsen/toolbelt.vitest": "0.13.4",
     "esbuild": "0.28.2",
-    "readyup": "0.45.1",
+    "readyup": "0.46.1",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.7",
+    "vite": "8.3.8",
     "vitest": "5.1.0",
     "yaml": "2.9.1"
   },

package/dist/esm/check-cache/config-check-cache.d.ts

@@ -1,17 +0,0 @@
-import type { NmrConfig } from '../types.js';
-/**
- * Rejects a `checkCache` name that does not resolve to any command. Both fields are read by name alone, so a
- * misspelt entry is inert: The command that it meant to name goes on running, indistinguishable from one that
- * cannot be cached at all.
- *
- * Because the test is resolvability rather than membership of the cacheable set, an `excludeCommands` entry
- * written against a name that a later release moves out of the defaults remains valid.
- *
- * Reads nothing while every name resolves in the merged registries, and reads a package's own `scripts` only
- * once a name is missing from them: Those are a resolution tier of their own; a name declared only there is
- * valid.
- *
- * Does nothing outside a monorepo root, where `checkCache` is a key that this tier does not honor. `assertTierKeys`
- * reports that, and of the two messages it is the one that names the real mistake.
- */
-export declare function assertResolvableCheckCacheCommands(config: NmrConfig, configPath: string, baseDir: string): void;