@williamthorsen/nmr 0.47.0 → 0.48.0

package/.meta/changelog.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.48.0",
+    "date": "2026-10-17",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds the `--delegate <host>` flag to `nmr`, which runs a command whose result is its exit status, such as `ci`, `check`, or a `test` command, on that host over SSH against the local working tree with its uncommitted and untracked files, and exits 255 when the delegation fails outside the command. (#1058)",
+            "hash": "dbd1714d65a833a258ebcc859d6aed130a3d9910",
+            "entry": 1
+          },
+          {
+            "description": "Adds the `NMR_DELEGATE` environment variable, which names the host on which `nmr` runs every command that can be delegated, and the `--no-delegate` flag, which runs a command on the local machine whatever `NMR_DELEGATE` names. (#1058)",
+            "hash": "dbd1714d65a833a258ebcc859d6aed130a3d9910",
+            "entry": 2
+          },
+          {
+            "description": "Adds the host to the verdict for a delegated command, as `passed on <host>` in the line and as a `host` field in the `--json` object. (#1058)",
+            "hash": "dbd1714d65a833a258ebcc859d6aed130a3d9910",
+            "entry": 3
+          }
+        ]
+      },
+      {
+        "title": "📦 Dependencies",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Upgrades `@williamthorsen/eslint-config-typescript` from 18.0.0 to 19.0.0 and rewrites the code in `build-info`, `nmr-core`, `nmr`, and `release-kit` that its new and widened rules report, without changing behavior. (#1047)",
+            "hash": "610ee159fdc429681b1078b500a064c5df296724",
+            "entry": 1
+          },
+          {
+            "description": "Upgrades `readyup` from 0.40.0 to 0.41.0 and recompiles the kits in `nmr`, `release-kit`, and `v11y-check`, whose manifests now record each checklist's check names under `checklistChecks`. (#1047)",
+            "hash": "610ee159fdc429681b1078b500a064c5df296724",
+            "entry": 2
+          },
+          {
+            "description": "Upgrades `pnpm` to 12.11.2, `@types/node` to 24.19.2, `lefthook` to 2.2.1, `@williamthorsen/strict-lint` to 14.2.0, `@williamthorsen/tsconfig` to 0.11.0, `smol-toml` to 1.9.1, and `vite` to 8.3.4. (#1047)",
+            "hash": "610ee159fdc429681b1078b500a064c5df296724",
+            "entry": 3
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.47.0",
     "date": "2026-10-15",

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.40.0";
+export const __readyupVersion = "0.41.0";
 import { createRequire as __rdyCreateRequire } from 'node:module';
 const require = __rdyCreateRequire(import.meta.url);
 
@@ -7442,10 +7442,11 @@ function findClosestName(name, candidates) {
   let shortestDistance = Infinity;
   for (const candidate of candidates) {
     const distance = measureDistance(name, candidate);
-    if (distance < shortestDistance) {
-      shortestDistance = distance;
-      closestName = candidate;
+    if (distance >= shortestDistance) {
+      continue;
     }
+    shortestDistance = distance;
+    closestName = candidate;
   }
   return shortestDistance <= ceiling ? closestName : void 0;
 }
@@ -8510,7 +8511,7 @@ var default_default = defineRdyKit({
         {
           name: ".config/nmr.config.ts uses defineConfig",
           severity: "recommend",
-          skip: () => !fileExists(".config/nmr.config.ts") ? "no nmr config file" : false,
+          skip: () => !fileExists(".config/nmr.config.ts") && "no nmr config file",
           check: () => fileContains(".config/nmr.config.ts", /defineConfig/),
           fix: "Wrap the config export with defineConfig() from @williamthorsen/nmr/config for type safety"
         },
@@ -8521,7 +8522,7 @@ var default_default = defineRdyKit({
             return `eslint >= ${MIN_ESLINT_VERSION}`;
           },
           severity: "error",
-          skip: () => !hasDevDependency("eslint") ? "eslint not installed" : false,
+          skip: () => !hasDevDependency("eslint") && "eslint not installed",
           check: hasSupportedEslintVersion,
           get fix() {
             return `pnpm add --save-dev eslint@^${MIN_ESLINT_VERSION}. Earlier releases resolve config from the working directory, so nmr's root lint and lint:check would apply the root config to every package`;
@@ -8532,7 +8533,7 @@ var default_default = defineRdyKit({
             return `@williamthorsen/strict-lint >= ${MIN_STRICT_LINT_VERSION}`;
           },
           severity: "error",
-          skip: () => !hasDevDependency("@williamthorsen/strict-lint") ? "strict-lint not installed" : false,
+          skip: () => !hasDevDependency("@williamthorsen/strict-lint") && "strict-lint not installed",
           check: hasSupportedStrictLintVersion,
           get fix() {
             return `pnpm add --save-dev @williamthorsen/strict-lint@^${MIN_STRICT_LINT_VERSION}. Earlier releases pin ESLint to one config and resolve ceilings from the working directory, so nmr's root lint:strict would report the wrong rules for every package`;
@@ -8939,7 +8940,7 @@ function formatPaths(paths) {
 ${paths.map((path7) => `      ${path7}`).join("\n")}`;
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.47.0" };
+  const pickedFields = { "version": "0.48.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }
@@ -9133,7 +9134,7 @@ function testSuiteGatesTestFileConventions(cwd = process.cwd()) {
 }
 function describeConventionsGuardSkip() {
   const guard = findConventionsGuard(process.cwd());
-  return guard === void 0 ? false : `reported by checkTestFileConventions in ${guard}`;
+  return guard !== void 0 && `reported by checkTestFileConventions in ${guard}`;
 }
 function findConventionsGuard(cwd) {
   return findTestFiles(cwd).find(
@@ -9170,7 +9171,7 @@ var NEVER_INSTALLED_PROGRAMS = /* @__PURE__ */ new Set(["corepack", "gh"]);
 var statusByCwd = /* @__PURE__ */ new Map();
 async function describeSelfHostedRunnerSkip(cwd = process.cwd(), readFacts) {
   const status = await getSelfHostedRunnerStatus(cwd, readFacts);
-  return "skip" in status ? status.skip : false;
+  return "skip" in status && status.skip;
 }
 function findSelfHostedRunnerFailures(facts, cwd) {
   const failures = [];

package/.readyup/manifest.json

@@ -19,6 +19,51 @@
         "wrap-ansi": "10.0.2",
         "yaml": "2.9.1"
       },
+      "checklistChecks": [
+        {
+          "checklist": "nmr",
+          "checks": [
+            "@williamthorsen/nmr in devDependencies",
+            "@williamthorsen/nmr >= 0.48.0",
+            "pnpm-workspace.yaml exists",
+            "catalogued dependencies use catalog:",
+            "package.json has packageManager field",
+            ".tool-versions does not list pnpm",
+            "no package.json declares a pnpm field",
+            "no package.json declares a workspaces field",
+            ".config/nmr.config.ts uses defineConfig",
+            "eslint >= 10.0.0",
+            "@williamthorsen/strict-lint >= 9.3.0",
+            "root package.json has no nmr-provided scripts",
+            "no root install script runs lefthook install unguarded",
+            "all workspace packages can build",
+            "every bin target is a committed wrapper",
+            "every bin wrapper's build-output target is covered by files",
+            "no retired Vitest config variants",
+            "every vitest.config builds on @williamthorsen/nmr/vitest",
+            "vitest.root.config.ts builds on @williamthorsen/nmr/vitest",
+            "every workspace with a Vite config has a Vitest config",
+            "the test suite gates the test-file conventions",
+            "every test file names its isolation tier",
+            "every test file is under a __tests__ directory",
+            "no package re-exports the ancestor Vitest config",
+            "Prettier config builds on @williamthorsen/nmr/prettier",
+            "taze.config.ts builds on @williamthorsen/nmr/taze",
+            "taze config declares no option taze discards",
+            "v11y-check in devDependencies",
+            "scripts/run-workspace-script.ts does not exist",
+            "no workspace packages reference run-workspace-script or \"pnpm run ws\""
+          ]
+        },
+        {
+          "checklist": "self-hosted runner",
+          "checks": [
+            "GitHub reports the repo's runner settings",
+            "CI_RUNS_ON selects the self-hosted runner",
+            "the self-hosted runner can run CI"
+          ]
+        }
+      ],
       "checklists": [
         "nmr",
         "self-hosted runner"
@@ -41,7 +86,7 @@
           "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
         },
         {
-          "hash": "211453c6",
+          "hash": "98509862",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
         },
@@ -56,7 +101,7 @@
           "path": "../../nmr-core/dist/esm/index.js"
         },
         {
-          "hash": "2507870d",
+          "hash": "89d3e3b4",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/parseArgs.js"
         },
@@ -81,12 +126,12 @@
           "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
         },
         {
-          "hash": "aaeb1a84",
+          "hash": "ffa13ccc",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "a06b470a",
+          "hash": "47f25de7",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -119,7 +164,7 @@
           "path": "../src/helpers/escapeControlCharacters.ts"
         },
         {
-          "hash": "47249ca4",
+          "hash": "2d1cf397",
           "kind": "module",
           "path": "../src/helpers/findClosestName.ts"
         },
@@ -186,10 +231,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.40.0",
+      "readyupVersion": "0.41.0",
       "source": "kits/default.ts",
-      "sourceHash": "aaeb1a84",
-      "targetHash": "125a39cc"
+      "sourceHash": "ffa13ccc",
+      "targetHash": "6baed250"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.48.0 — 2026-10-17
+
+### 🎉 Features
+
+- Adds the `--delegate <host>` flag to `nmr`, which runs a command whose result is its exit status, such as `ci`, `check`, or a `test` command, on that host over SSH against the local working tree with its uncommitted and untracked files, and exits 255 when the delegation fails outside the command. (#1058)
+- Adds the `NMR_DELEGATE` environment variable, which names the host on which `nmr` runs every command that can be delegated, and the `--no-delegate` flag, which runs a command on the local machine whatever `NMR_DELEGATE` names. (#1058)
+- Adds the host to the verdict for a delegated command, as `passed on <host>` in the line and as a `host` field in the `--json` object. (#1058)
+
+### 📦 Dependencies
+
+- Upgrades `@williamthorsen/eslint-config-typescript` from 18.0.0 to 19.0.0 and rewrites the code in `build-info`, `nmr-core`, `nmr`, and `release-kit` that its new and widened rules report, without changing behavior. (#1047)
+- Upgrades `readyup` from 0.40.0 to 0.41.0 and recompiles the kits in `nmr`, `release-kit`, and `v11y-check`, whose manifests now record each checklist's check names under `checklistChecks`. (#1047)
+- Upgrades `pnpm` to 12.11.2, `@types/node` to 24.19.2, `lefthook` to 2.2.1, `@williamthorsen/strict-lint` to 14.2.0, `@williamthorsen/tsconfig` to 0.11.0, `smol-toml` to 1.9.1, and `vite` to 8.3.4. (#1047)
+
 ## 0.47.0 — 2026-10-15
 
 ### 🎉 Features

package/README.md

@@ -5,15 +5,13 @@
 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 — v0.47.0 (2026-10-15)
+## Release notes — v0.48.0 (2026-10-17)
 
 ### 🎉 Features
 
-- Sets `maxWorkers` on every project built by `defineVitestConfig` and `defineRootVitestConfig` to one worker per 4 GiB of total memory, bounded by one fewer than the core count, in place of Vitest's default of one fewer than the core count, which does not take memory into account; machines with 2 or fewer cores keep 3 workers. (#1044)
-- Applies the `--maxWorkers` (or `--max-workers`) flag to every project, which Vitest does not do itself, making the flag override both the derived count and a `maxWorkers` set through the `project` or `tiers` seam, while the `VITEST_MAX_WORKERS` environment variable still overrides the flag. (#1044)
-- Adds a machine lock that makes a heavy command (`check`, `ci`, and every `test` command except `test:watch`) wait, printing `nmr: waiting for …`, until the heavy command already running on the machine finishes; a nested command and a `-R` or `-F` fan-out take the lock once, and a cached pass does not wait. (#1045)
-- Adds the `--no-lock` flag and the `NMR_NO_LOCK=1` environment variable, which run a command and the commands nested in it without waiting for the machine lock, for example on a self-hosted CI machine that runs several runners in parallel. (#1045)
-- Extends the `nmr` rulebook to state that a run printing `nmr: waiting for …` is waiting for the machine lock rather than stuck, and that an agent must neither kill it nor rerun it with `--no-lock`. (#1045)
+- Adds the `--delegate <host>` flag to `nmr`, which runs a command whose result is its exit status, such as `ci`, `check`, or a `test` command, on that host over SSH against the local working tree with its uncommitted and untracked files, and exits 255 when the delegation fails outside the command. (#1058)
+- Adds the `NMR_DELEGATE` environment variable, which names the host on which `nmr` runs every command that can be delegated, and the `--no-delegate` flag, which runs a command on the local machine whatever `NMR_DELEGATE` names. (#1058)
+- Adds the host to the verdict for a delegated command, as `passed on <host>` in the line and as a `host` field in the `--json` object. (#1058)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -195,6 +193,17 @@ nmr: waiting for test in /Users/me/repos/other-repo (pid 41872) to finish
 
 The lock lives in `/tmp/nmr-<uid>/`, or in `NMR_LOCK_DIR`; a sandboxed session needs write access to it. `nmr --no-lock <command>` or `NMR_NO_LOCK=1` runs without waiting. [Machine lock](docs/machine-lock.md) covers which commands take it, nesting and fan-outs, reclaiming a lock that its holder left behind, and CI.
 
+## Delegating to another machine
+
+`nmr --delegate <host> <command>` runs the command on another machine over SSH, against this working tree, and exits with its status. `NMR_DELEGATE=<host>` makes that the default:
+
+```console
+$ nmr --delegate imac2 ci
+✅ my-repo: ci: passed on imac2 in 1m 48s
+```
+
+[Delegating to another machine](docs/delegate.md) covers which commands can be delegated, what the host runs, how failures are reported, and setting up the host.
+
 ## Shared configs and helpers
 
 ### Shared Vitest config
@@ -299,6 +308,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 - [What nmr reports](docs/reporting.md): Verdicts, `--json`, output style, and verbosity
 - [Check-result cache](docs/check-cache.md): What is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
 - [Machine lock](docs/machine-lock.md): Which commands wait for one another, where the lock lives, and bypassing it
+- [Delegating to another machine](docs/delegate.md): `--delegate`, `NMR_DELEGATE`, what the host runs, and setting it up
 - [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, `report-catalog`, `report-overrides`, and `nmr-taze`
 - [Standalone utilities](docs/utilities.md): `nmr-clean`, `nmr-compile`, `nmr-fmt`, and `ensure-prepublish-hooks`
 - [Shared Vitest config](docs/vitest.md): Test tiers, test selections, the conventions check, and customization

package/agents/guidance/rulebooks/nmr.md

@@ -15,4 +15,5 @@ delivery: ambient
 - Every command that nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command into which it expands. Those are the words that a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. The lines print in every verbosity, so `nmr -q <command>` is the low-noise way to run rather than a silent one: It withholds the output of the commands that nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. nmr reads its own flags only before the command name and passes everything after the name to the commands that run: `nmr ci -q` hands `-q` to `nmr-fmt`, which rejects it. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
 - Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing that the test reaches -- `tool` (a process that the test starts, or a program other than the package's own code that the test makes do its work, including an embedded engine, which the package installs and the test runs in-process, such as PGlite), `localhost` (a service already running on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --sources` reports both and warns that the check is missing.
 - A heavy command (`check`, `ci`, and the `test` commands but `test:watch`) may print `nmr: waiting for <command> in <dir> (pid <pid>) to finish` and wait: nmr runs one at a time on the machine, across every repository. The run is not stuck, and it continues once the holder ends. Do not kill it, and do not rerun it with `--no-lock` to get past the wait, which defeats the memory protection that the lock exists for. A warning that nmr is `running without the machine lock` names a directory that the sandbox cannot write.
-- The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; `machine-lock.md` for which commands take the machine lock, where it lives, and its bypass; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.
+- A verdict reading `passed on <host>` or `failed on <host>` reports a command that ran on another machine, because `--delegate` or `NMR_DELEGATE` sent it there; the output above it is the host's. Exit 255 with `could not prepare <host>` inside a sandbox means that the sandbox refused `ssh`: Ask for network access to the host rather than treating the host as broken, or run the command here with `nmr --no-delegate <command>`.
+- The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; `machine-lock.md` for which commands take the machine lock, where it lives, and its bypass; `delegate.md` for which commands `--delegate` runs on another machine, what the host runs, and its setup; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.

package/dist/esm/bin-path.js

@@ -9,10 +9,11 @@ export function prependBinDirs(options) {
     const additions = [];
     for (const dir of [anchorDir, monorepoRoot]) {
         const binDir = path.resolve(dir, 'node_modules', '.bin');
-        if (!seen.has(binDir)) {
-            seen.add(binDir);
-            additions.push(binDir);
+        if (seen.has(binDir)) {
+            continue;
         }
+        seen.add(binDir);
+        additions.push(binDir);
     }
     if (additions.length === 0) {
         return env;

package/dist/esm/commands/fmt.js

@@ -126,7 +126,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
 function classifyListedFile(cwd, file) {
     try {
         const stats = lstatSync(path.resolve(cwd, file), { throwIfNoEntry: false });
-        return stats?.isFile() === true ? { kind: 'formattable' } : { kind: 'excluded' };
+        return { kind: stats?.isFile() === true ? 'formattable' : 'excluded' };
     }
     catch (error) {
         const code = UNREADABLE_CODES.find((candidate) => hasErrnoCode(error, candidate));

package/dist/esm/help.js

@@ -1,5 +1,6 @@
 import { isHookName } from "./helpers/hook-name.js";
 import { OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG } from "./output-style.js";
+import { DELEGATE_ENV_VAR } from "./remote-run.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 const LIFECYCLE_SCRIPT_NAMES = new Set([
     'dependencies',
@@ -32,15 +33,18 @@ export function generateHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
         '  -R, --recursive             Run command in all packages',
         '  -w, --workspace-root        Use root scripts, running at the monorepo root',
         "  -q, --quiet                 Suppress command output, keeping nmr's verdicts",
+        '      --delegate <host>       Run on <host> over SSH, against this working tree',
         '      --json                  Report one JSON object per command, withholding command output',
         '      --log                   Print the recorded run instead of running (up to 256 KiB)',
         '      --no-cache              Run even if this tree already passed; record the result',
+        '      --no-delegate           Run here, even when NMR_DELEGATE names a host',
         '      --no-lock               Run without waiting for another heavy command on this machine',
         `      ${OUTPUT_STYLE_FLAG} <style>  Output style: auto (default), plain, or rich`,
         '  -?, --help                  Show this help',
         '  -V, --version               Show version number',
         '',
         'Environment:',
+        `  ${DELEGATE_ENV_VAR}                Host on which to run each command that can be delegated`,
         `  ${OUTPUT_STYLE_ENV_VAR}            Output style: auto (default), plain, or rich. auto prints`,
         '                              plain, without emoji, when CI is set or the stream is not a terminal.',
         '',

package/dist/esm/helpers/findClosestName.js

@@ -4,10 +4,11 @@ export function findClosestName(name, candidates) {
     let shortestDistance = Infinity;
     for (const candidate of candidates) {
         const distance = measureDistance(name, candidate);
-        if (distance < shortestDistance) {
-            shortestDistance = distance;
-            closestName = candidate;
+        if (distance >= shortestDistance) {
+            continue;
         }
+        shortestDistance = distance;
+        closestName = candidate;
     }
     return shortestDistance <= ceiling ? closestName : undefined;
 }

package/dist/esm/helpers/quoteForShell.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shell-escapes a single argument by wrapping in single quotes
+ * and escaping any embedded single quotes.
+ */
+export declare function quoteForShell(arg: string): string;

package/dist/esm/helpers/quoteForShell.js

@@ -0,0 +1,3 @@
+export function quoteForShell(arg) {
+    return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
+}

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

@@ -0,0 +1,136 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** Names the host to which nmr delegates a command when the invocation does not say otherwise. */
+export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
+/** The flag that names the host on which to run the command. */
+export declare const DELEGATE_FLAG = "--delegate";
+/** The exit status of a delegation that failed outside its command, which matches `ssh`'s own. */
+export declare const DELEGATION_FAILURE_EXIT_CODE = 255;
+/** The flag that runs the command here, whatever `NMR_DELEGATE` names. */
+export declare const NO_DELEGATE_FLAG = "--no-delegate";
+/** Keeps `ssh` from prompting or waiting on a terminal, and bounds the wait for a host that does not answer. */
+export declare const SSH_OPTIONS: readonly string[];
+/** Where a delegation runs, or why the invocation cannot run where it asked to. */
+export type DelegationTarget = {
+    kind: 'local';
+} | {
+    kind: 'remote';
+    host: string;
+    source: 'env' | 'flag';
+} | {
+    kind: 'refused';
+    error: string;
+};
+/** The phases of a delegation that run on the host, each reported by name when it fails. */
+export type RemotePhase = 'check out' | 'install' | 'prepare' | 'push' | 'run';
+/** The status of a delegated command, or the phase that kept it from finishing and what that phase printed. */
+export type RemoteRunResult = {
+    ok: true;
+    exitCode: number;
+} | {
+    ok: false;
+    message: string;
+    output: string;
+    phase: RemotePhase;
+};
+/** A commit that records the working tree, or why one could not be made. */
+export type SnapshotResult = {
+    ok: true;
+    sha: string;
+    toplevel: string;
+} | {
+    ok: false;
+    isUnsupported: boolean;
+    reason: string;
+};
+/**
+ * Composes the script that runs nmr on the host, from the directory that corresponds to the local one.
+ *
+ * A Node launcher starts nmr in its own process group, with stdin closed, and reads the connection's stdin, which the
+ * local `ssh` holds open and closes when it exits, as on Ctrl-C; on that end of input, the launcher stops nmr's whole
+ * group, so that an interrupted run does not continue on the host. The launcher rather than the shell's job control
+ * makes the group, because a shell such as dash refuses job control without a terminal. `--no-delegate` keeps a host
+ * whose environment sets `NMR_DELEGATE` from passing the command on again.
+ *
+ * The script writes nmr's status to `statusPath` before it exits, so that a 255 from `ssh` can be told apart: It is
+ * nmr's own when the file records it, and a dropped connection otherwise.
+ *
+ * @internal
+ */
+export declare function composeRunScript(options: {
+    nmrArgs: readonly string[];
+    remoteEnv: Readonly<Record<string, string>>;
+    runDir: string;
+    statusPath: string;
+}): string;
+/**
+ * Builds a commit whose tree is the working tree as it is on disk: tracked changes, staged or not, and untracked
+ * files that git does not ignore. The commit is built in a temporary index, so the repository's index, refs, and
+ * stash are untouched; the only write is to the object database.
+ *
+ * The identity and date are fixed, so that the same tree on the same `HEAD` always yields the same commit and a
+ * repeated push transfers nothing. A submodule, or a nested repository that `git add` would record as one, is
+ * refused: Its content is in a repository that the snapshot does not include.
+ */
+export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): SnapshotResult;
+/**
+ * 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.
+ *
+ * @internal
+ */
+export declare function deriveCheckoutPath(hostname: string, toplevel: string): string;
+/**
+ * Renders the warning for a `--delegate` or `--no-delegate` that appears after the command name, which makes it an
+ * argument to the command rather than a flag to nmr.
+ */
+export declare function formatMisplacedDelegationWarning(command: string, style: OutputStyle): string;
+/**
+ * Decides where an invocation runs. `--no-delegate` outranks `--delegate`, which outranks `NMR_DELEGATE`.
+ *
+ * A command that rewrites the tree, or that runs until it is stopped, cannot be delegated, and neither can `--log`,
+ * which reads this machine's recordings. Asked for by the flag, such an invocation is refused; asked for by the
+ * variable, which sets a default for every invocation, it runs here.
+ */
+export declare function resolveDelegationTarget(options: {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    flagHost: string | undefined;
+    isOptedOut: boolean;
+    isReading: boolean;
+}): DelegationTarget;
+/**
+ * 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
+ * delegations from different worktrees do not share a checkout, and `node_modules` and build output persist
+ * between runs. Each phase is its own connection, so that a failure names its phase; 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: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    host: string;
+    monorepoRoot: string;
+    nmrArgs: readonly string[];
+    remoteEnv: Readonly<Record<string, string>>;
+    snapshot: {
+        sha: string;
+        toplevel: string;
+    };
+    stderr: Writable;
+    stdout: Writable;
+}): Promise<RemoteRunResult>;
+/**
+ * Wraps a script to run under `/bin/sh` with the `PATH` that the user's interactive login shell sets. pnpm's own
+ * installer and the common version managers set it up in the interactive startup file, such as `~/.zshrc`, which a
+ * non-interactive shell does not read. The script runs under `sh` rather than that shell itself, because the login
+ * shell, such as fish, may not accept the POSIX syntax in which the scripts are written.
+ *
+ * A startup file may print to stdout, so the shell prints `PATH` after a marker, and only what follows the last
+ * marker is read. When no marker arrives, the script keeps the `PATH` with which `ssh` started it.
+ *
+ * @internal
+ */
+export declare function wrapRemoteScript(script: string): string;

package/dist/esm/remote-run.js

@@ -0,0 +1,251 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GIT_OUTPUT_LIMIT, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+import { quoteForShell } from "./helpers/quoteForShell.js";
+export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
+export const DELEGATE_FLAG = '--delegate';
+export const DELEGATION_FAILURE_EXIT_CODE = 255;
+export const NO_DELEGATE_FLAG = '--no-delegate';
+export const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10'];
+export function composeRunScript(options) {
+    const { nmrArgs, remoteEnv, runDir, statusPath } = options;
+    const assignments = Object.entries(remoteEnv).map(([name, value]) => `${name}=${quoteForShell(value)}`);
+    const invocation = [
+        ...assignments,
+        'node',
+        '-e',
+        quoteForShell(RUN_LAUNCHER_SOURCE),
+        'pnpm',
+        'exec',
+        'nmr',
+        '--no-delegate',
+        ...nmrArgs.map(quoteForShell),
+    ].join(' ');
+    return [
+        `rm -f ${statusPath}`,
+        `mkdir -p ${runDir} && cd ${runDir} || exit 1`,
+        invocation,
+        'nmr_status=$?',
+        String.raw `printf '%s\n' "$nmr_status" > ${statusPath}`,
+        'exit "$nmr_status"',
+    ].join('\n');
+}
+export function createSnapshot(cwd, env) {
+    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
+    if (!toplevelResult.ok) {
+        return { ok: false, isUnsupported: true, reason: `not a git repository: ${toplevelResult.error}` };
+    }
+    const toplevel = toplevelResult.stdout.trim();
+    if (fs.existsSync(path.join(toplevel, '.gitmodules'))) {
+        return { ok: false, isUnsupported: true, reason: 'the repository declares submodules' };
+    }
+    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, env);
+    if (!indexPathResult.ok) {
+        return { ok: false, isUnsupported: false, reason: indexPathResult.error };
+    }
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nmr-snapshot-'));
+    try {
+        const tempIndex = path.join(tempDir, 'index');
+        const indexPath = path.resolve(toplevel, indexPathResult.stdout.trim());
+        if (fs.existsSync(indexPath)) {
+            fs.copyFileSync(indexPath, tempIndex);
+        }
+        const indexEnv = { ...env, GIT_INDEX_FILE: tempIndex };
+        const addResult = runGit(['add', '--all'], toplevel, indexEnv);
+        if (!addResult.ok) {
+            return { ok: false, isUnsupported: false, reason: addResult.error };
+        }
+        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, indexEnv);
+        if (!stageResult.ok) {
+            return { ok: false, isUnsupported: false, reason: stageResult.error };
+        }
+        if (stageResult.stdout.split('\0').some((entry) => entry.startsWith('160000 '))) {
+            return { ok: false, isUnsupported: true, reason: 'the working tree contains a submodule or a nested repository' };
+        }
+        const treeResult = runGit(['write-tree'], toplevel, indexEnv);
+        if (!treeResult.ok) {
+            return { ok: false, isUnsupported: false, reason: treeResult.error };
+        }
+        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, env);
+        const parentArgs = headResult.ok ? ['-p', headResult.stdout.trim()] : [];
+        const commitResult = runGit(['commit-tree', treeResult.stdout.trim(), ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, { ...env, ...SNAPSHOT_IDENTITY_ENV });
+        if (!commitResult.ok) {
+            return { ok: false, isUnsupported: false, reason: commitResult.error };
+        }
+        return { ok: true, sha: commitResult.stdout.trim(), toplevel };
+    }
+    finally {
+        fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+}
+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));
+}
+export function formatMisplacedDelegationWarning(command, style) {
+    return (`${STATUS_GLYPHS[style].warning.text} ${DELEGATE_FLAG} and ${NO_DELEGATE_FLAG} after the command name are passed ` +
+        `to \`${command}\`, not read by nmr. Did you mean \`nmr ${DELEGATE_FLAG} <host> ${command}\`?`);
+}
+export function resolveDelegationTarget(options) {
+    const { command, env, flagHost, isOptedOut, isReading } = options;
+    if (isOptedOut) {
+        return { kind: 'local' };
+    }
+    const isDelegable = !isReading && !NON_DELEGABLE_COMMANDS.has(command);
+    if (flagHost !== undefined) {
+        if (isDelegable) {
+            return { kind: 'remote', host: flagHost, source: 'flag' };
+        }
+        const subject = isReading ? '--log' : `\`${command}\``;
+        return {
+            kind: 'refused',
+            error: `${subject} cannot be delegated: it ${isReading ? "reads this machine's recordings" : 'rewrites the working tree or runs until stopped'}. Run it without ${DELEGATE_FLAG}.`,
+        };
+    }
+    const envHost = env[DELEGATE_ENV_VAR];
+    if (envHost !== undefined && envHost !== '' && isDelegable) {
+        return { kind: 'remote', host: envHost, source: 'env' };
+    }
+    return { kind: 'local' };
+}
+export async function runRemotely(options) {
+    const { cwd, env, host, monorepoRoot, nmrArgs, remoteEnv, 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);
+    if (prepare.exitCode !== 0) {
+        return { ok: false, message: `could not prepare ${host}`, output: prepare.output, phase: 'prepare' };
+    }
+    const push = await runProcess([
+        'git',
+        'push',
+        '--force',
+        '--no-verify',
+        '--quiet',
+        `--receive-pack=${RECEIVE_PACK_COMMAND}`,
+        `${host}:${checkoutPath}`,
+        `${snapshot.sha}:${SNAPSHOT_REF}`,
+    ], { cwd: snapshot.toplevel, env: { ...env, GIT_SSH_COMMAND: ['ssh', ...SSH_OPTIONS].join(' ') } });
+    if (push.exitCode !== 0) {
+        return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push' };
+    }
+    const checkout = await runSsh(host, `cd ${checkoutDir} && git checkout --quiet --force --detach ${snapshot.sha} && git clean --force -d --quiet`, env);
+    if (checkout.exitCode !== 0) {
+        return { ok: false, message: `could not check out on ${host}`, output: checkout.output, phase: 'check out' };
+    }
+    const rootDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, monorepoRoot));
+    const install = await runSsh(host, `cd ${rootDir} && CI=true pnpm install --frozen-lockfile`, env);
+    if (install.exitCode !== 0) {
+        const message = install.exitCode === COMMAND_NOT_FOUND_EXIT_CODE
+            ? `could not install on ${host}: pnpm is not on the PATH that the interactive login shell sets there`
+            : `could not install on ${host}`;
+        return { ok: false, message, output: install.output, phase: 'install' };
+    }
+    const runDir = joinRemotePath(checkoutDir, path.relative(snapshot.toplevel, cwd));
+    const statusPath = `${checkoutDir}/.git/${quoteForShell(RUN_STATUS_FILE)}`;
+    const run = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(composeRunScript({ nmrArgs, remoteEnv, runDir, statusPath }))], {
+        env,
+        isStreaming: true,
+        stderr,
+        stdout,
+    });
+    if (run.exitCode === DELEGATION_FAILURE_EXIT_CODE) {
+        const recorded = await runSsh(host, `cat ${statusPath}`, env);
+        if (recorded.exitCode !== 0 || recorded.output.trim() !== String(DELEGATION_FAILURE_EXIT_CODE)) {
+            return { ok: false, message: `lost connection to ${host}`, output: '', phase: 'run' };
+        }
+    }
+    return { ok: true, exitCode: run.exitCode };
+}
+export function wrapRemoteScript(script) {
+    return `exec /bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}\n${script}`)}`;
+}
+const PATH_MARKER = '__NMR_LOGIN_PATH__=';
+const LOGIN_PATH_PREAMBLE = [
+    `nmr_login_path=$("\${SHELL:-/bin/sh}" -ilc 'printf "\\n${PATH_MARKER}%s\\n" "$PATH"' </dev/null 2>/dev/null | sed -n 's/^${PATH_MARKER}//p' | tail -n 1)`,
+    '[ -n "$nmr_login_path" ] && PATH=$nmr_login_path',
+    'export PATH',
+].join('; ');
+const RECEIVE_PACK_COMMAND = `/bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}; exec git receive-pack "$1"`)} nmr-receive-pack`;
+const RUN_LAUNCHER_SOURCE = [
+    "const { spawn } = require('node:child_process');",
+    "const { constants } = require('node:os');",
+    'const [file, ...args] = process.argv.slice(1);',
+    "const child = spawn(file, args, { detached: true, stdio: ['ignore', 'inherit', 'inherit'] });",
+    "const stop = () => { try { process.kill(-child.pid, 'SIGTERM'); } catch {} };",
+    "process.stdin.on('end', stop).on('error', stop).resume();",
+    "child.on('error', (error) => { console.error(file + ': ' + error.message); process.exit(127); });",
+    "child.on('close', (code, signal) => process.exit(code ?? 128 + (constants.signals[signal] ?? 0)));",
+].join('\n');
+const RUN_STATUS_FILE = 'nmr-run-status';
+const COMMAND_NOT_FOUND_EXIT_CODE = 127;
+const PHASE_OUTPUT_LIMIT_BYTES = 65_536;
+const NON_DELEGABLE_BASE_COMMANDS = ['build', 'clean', 'compile', 'fix', 'fmt', 'lint', 'test:watch', 'upgrade'];
+const NON_DELEGABLE_COMMANDS = new Set([
+    ...NON_DELEGABLE_BASE_COMMANDS,
+    ...NON_DELEGABLE_BASE_COMMANDS.map((command) => `root:${command}`),
+]);
+const SNAPSHOT_IDENTITY_ENV = {
+    GIT_AUTHOR_DATE: '@0 +0000',
+    GIT_AUTHOR_EMAIL: 'nmr@localhost',
+    GIT_AUTHOR_NAME: 'nmr delegate',
+    GIT_COMMITTER_DATE: '@0 +0000',
+    GIT_COMMITTER_EMAIL: 'nmr@localhost',
+    GIT_COMMITTER_NAME: 'nmr delegate',
+};
+const SNAPSHOT_REF = 'refs/nmr/delegate';
+function forwardChunk(chunk, stream, buffer) {
+    if (stream === undefined) {
+        buffer.append(chunk);
+        return;
+    }
+    stream.write(chunk);
+}
+function joinRemotePath(checkoutDir, relativeDir) {
+    const posixDir = relativeDir.split(path.sep).join('/');
+    return posixDir === '' ? checkoutDir : `${checkoutDir}/${quoteForShell(posixDir)}`;
+}
+function runGit(args, cwd, env) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT });
+    if (result.error !== undefined) {
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ok: false, error: result.stderr.trim() || `git ${args[0] ?? ''} exited ${result.status ?? 'abnormally'}` };
+    }
+    return { ok: true, stdout: result.stdout };
+}
+function runProcess(argv, options) {
+    const { cwd, env, isStreaming = false, stderr, stdout } = options;
+    const [file = '', ...args] = argv;
+    const buffer = createBoundedBuffer({
+        headLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
+        tailLimitBytes: PHASE_OUTPUT_LIMIT_BYTES,
+    });
+    return new Promise((resolve) => {
+        const child = spawn(file, args, { cwd, env, stdio: [isStreaming ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+        child.stdout?.on('data', (chunk) => {
+            forwardChunk(chunk, isStreaming ? stdout : undefined, buffer);
+        });
+        child.stderr?.on('data', (chunk) => {
+            forwardChunk(chunk, isStreaming ? stderr : undefined, buffer);
+        });
+        child.on('error', (error) => {
+            resolve({ exitCode: COMMAND_NOT_FOUND_EXIT_CODE, output: `${file}: ${error.message}` });
+        });
+        child.on('close', (code, signal) => {
+            child.stdin?.destroy();
+            resolve({
+                exitCode: code ?? 128 + (signal === null ? 0 : os.constants.signals[signal]),
+                output: buffer.readBuffer().toString('utf8'),
+            });
+        });
+    });
+}
+function runSsh(host, script, env) {
+    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env });
+}

package/dist/esm/runCli.js

@@ -14,10 +14,12 @@ import { readFilterSelection } from "./helpers/filter-selection.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
+import { quoteForShell } from "./helpers/quoteForShell.js";
 import { composeTranscript } from "./helpers/transcript.js";
 import { acquireMachineLock, formatMisplacedNoLockWarning, HEAVY_COMMANDS, LOCK_TOKEN_ENV_VAR, NO_LOCK_ENV_VAR, } from "./machine-lock.js";
 import { isTerminalStream, OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG, resolveOutputStyles } from "./output-style.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
+import { createSnapshot, DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATION_FAILURE_EXIT_CODE, formatMisplacedDelegationWarning, NO_DELEGATE_FLAG, resolveDelegationTarget, runRemotely, } from "./remote-run.js";
 import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
 import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, readPackageJsonScripts, resolveScript, } from "./resolver.js";
@@ -38,6 +40,10 @@ export async function runCli(options) {
         return { exitCode: established.result.exitCode };
     }
     const invocation = established.value;
+    const delegated = await runOnDelegateHost(invocation);
+    if (delegated !== undefined) {
+        return delegated;
+    }
     const planned = await planRun(invocation);
     const { exitCode, isUnknownCommand = false } = planned.settled ? planned.result : await executePlan(planned.value);
     if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(options.env)) {
@@ -92,6 +98,7 @@ async function establishInvocation(options) {
             anchorDir,
             command: parsedArgs.command,
             context,
+            cwd,
             env,
             format,
             parsedArgs,
@@ -253,6 +260,77 @@ async function executePlan(plan) {
     reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
+async function runOnDelegateHost(invocation) {
+    const { command, context, cwd, env, format, parsedArgs, scope, stderr, stdout, styles } = invocation;
+    if (parsedArgs.passthrough.some(isDelegationFlag)) {
+        stderr.write(`${formatMisplacedDelegationWarning(command, styles.stderr)}
+`);
+    }
+    const target = resolveDelegationTarget({
+        command,
+        env,
+        flagHost: parsedArgs.delegateHost,
+        isOptedOut: parsedArgs.shouldRunLocally,
+        isReading: parsedArgs.shouldPrintLog,
+    });
+    if (target.kind === 'local') {
+        return undefined;
+    }
+    if (target.kind === 'refused') {
+        reportError(target.error, stderr);
+        return { exitCode: 1 };
+    }
+    const { host } = target;
+    const startedAtMs = Date.now();
+    const snapshot = createSnapshot(cwd, env);
+    if (!snapshot.ok && snapshot.isUnsupported) {
+        if (target.source === 'flag') {
+            reportError(`Cannot delegate to ${host}: ${snapshot.reason}`, stderr);
+            return { exitCode: 1 };
+        }
+        stderr.write(`nmr: running ${command} here rather than on ${host}: ${snapshot.reason}\n`);
+        return undefined;
+    }
+    const result = snapshot.ok
+        ? await runRemotely({
+            cwd,
+            env,
+            host,
+            monorepoRoot: context.monorepoRoot,
+            nmrArgs: composeForwardedArgs(command, parsedArgs),
+            remoteEnv: {
+                [COMMAND_VERBOSITY_ENV_VAR]: invocation.verbosity,
+                [OUTPUT_STYLE_ENV_VAR]: styles.stdout,
+                [REPORT_FORMAT_ENV_VAR]: format,
+            },
+            snapshot,
+            stderr,
+            stdout,
+        })
+        : { ok: false, message: 'could not snapshot the working tree', output: snapshot.reason };
+    const durationMs = Date.now() - startedAtMs;
+    if (!result.ok) {
+        if (result.output.trim() !== '') {
+            stderr.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+        }
+        const verdict = {
+            command,
+            detail: result.message,
+            durationMs,
+            exitCode: DELEGATION_FAILURE_EXIT_CODE,
+            host,
+            outcome: 'failed',
+            scope,
+        };
+        reportVerdict(verdict, stdout, format, styles.stdout);
+        return { exitCode: DELEGATION_FAILURE_EXIT_CODE };
+    }
+    const outcome = result.exitCode === 0
+        ? { outcome: 'passed', durationMs }
+        : { outcome: 'failed', durationMs, exitCode: result.exitCode };
+    reportVerdict({ command, host, scope, ...outcome }, stdout, format, styles.stdout);
+    return { exitCode: result.exitCode };
+}
 const FILTER_FLAGS = new Set(['-F', '--filter']);
 const BOOLEAN_FLAGS = new Map([
     ['-?', 'shouldShowHelp'],
@@ -260,6 +338,7 @@ const BOOLEAN_FLAGS = new Map([
     ['--json', 'shouldEmitJson'],
     ['--log', 'shouldPrintLog'],
     ['--no-cache', 'shouldBypassCache'],
+    [NO_DELEGATE_FLAG, 'shouldRunLocally'],
     ['--no-lock', 'shouldBypassLock'],
     ['-q', 'quiet'],
     ['--quiet', 'quiet'],
@@ -273,8 +352,9 @@ const BOOLEAN_FLAGS = new Map([
 function buildChildEnv(options) {
     const { env, format, passthrough, runId, shouldBypassCache, shouldBypassLock, snapshot, styles, verbosity } = options;
     const bypassesCache = shouldBypassCache || passthrough.length > 0;
+    const { [DELEGATE_ENV_VAR]: _delegateHost, ...inheritedEnv } = env;
     return {
-        ...env,
+        ...inheritedEnv,
         ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
         ...(bypassesCache && { [NO_CACHE_ENV_VAR]: '1' }),
         ...(shouldBypassLock && { [NO_LOCK_ENV_VAR]: '1' }),
@@ -340,6 +420,19 @@ function composeDelegation(options) {
         },
     };
 }
+function composeForwardedArgs(command, parsedArgs) {
+    return [
+        ...(parsedArgs.filter === undefined ? [] : ['--filter', parsedArgs.filter]),
+        ...(parsedArgs.recursive ? ['--recursive'] : []),
+        ...(parsedArgs.isWorkspaceRoot ? ['--workspace-root'] : []),
+        ...(parsedArgs.quiet ? ['--quiet'] : []),
+        ...(parsedArgs.shouldEmitJson ? ['--json'] : []),
+        ...(parsedArgs.shouldBypassCache ? ['--no-cache'] : []),
+        ...(parsedArgs.shouldBypassLock ? ['--no-lock'] : []),
+        command,
+        ...parsedArgs.passthrough,
+    ];
+}
 async function composeRetention(options) {
     const { anchorDir, command, key, retainedOutput, runId } = options;
     if (retainedOutput !== undefined) {
@@ -662,6 +755,7 @@ function parseArgs(args) {
         shouldBypassLock: false,
         shouldEmitJson: false,
         shouldPrintLog: false,
+        shouldRunLocally: false,
         shouldShowHelp: false,
         shouldShowVersion: false,
         passthrough: [],
@@ -696,6 +790,15 @@ function parseArgs(args) {
             index += styleArgument.consumedCount;
             continue;
         }
+        const delegateArgument = readDelegateArgument(args, index);
+        if (delegateArgument !== undefined) {
+            if (!delegateArgument.ok) {
+                return delegateArgument;
+            }
+            parsedArgs.delegateHost = delegateArgument.value;
+            index += delegateArgument.consumedCount;
+            continue;
+        }
         parsedArgs.command = arg;
         parsedArgs.passthrough = args.slice(index + 1);
         break;
@@ -742,18 +845,24 @@ function readPresentation(options) {
     }
     return { ok: true, format: format.format, styles, verbosity: verbosity.verbosity };
 }
-function readOutputStyleArgument(args, index) {
+function readDelegateArgument(args, index) {
+    return readFlagValue(args, index, DELEGATE_FLAG, 'a host argument');
+}
+function readFlagValue(args, index, flag, requirement) {
     const arg = args[index] ?? '';
-    const assignment = arg.startsWith(`${OUTPUT_STYLE_FLAG}=`) ? arg.slice(OUTPUT_STYLE_FLAG.length + 1) : undefined;
-    if (arg !== OUTPUT_STYLE_FLAG && assignment === undefined) {
+    const assignment = arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : undefined;
+    if (arg !== flag && assignment === undefined) {
         return undefined;
     }
     const value = assignment ?? args[index + 1];
     if (!value) {
-        return { ok: false, error: `${OUTPUT_STYLE_FLAG} requires a value argument: auto, plain, or rich` };
+        return { ok: false, error: `${flag} requires ${requirement}` };
     }
     return { ok: true, value, consumedCount: assignment === undefined ? 2 : 1 };
 }
+function readOutputStyleArgument(args, index) {
+    return readFlagValue(args, index, OUTPUT_STYLE_FLAG, 'a value argument: auto, plain, or rich');
+}
 function readRunnableSteps(resolvedScript, workspacePackageDirs) {
     if (workspacePackageDirs.length > 0) {
         return { isEmptiedByWorkspace: false, steps: resolvedScript.steps };
@@ -1004,6 +1113,9 @@ function isDefinedInAnyScope(command, context) {
     }
     return [context.monorepoRoot, ...context.workspacePackageDirs].some((dir) => Object.hasOwn(readPackageJsonScripts(dir) ?? {}, command));
 }
+function isDelegationFlag(arg) {
+    return arg === DELEGATE_FLAG || arg === NO_DELEGATE_FLAG || arg.startsWith(`${DELEGATE_FLAG}=`);
+}
 function isTopLevelInvocation(env) {
     const runId = env[RUN_ID_ENV_VAR];
     return runId === undefined || runId === '';
@@ -1032,8 +1144,8 @@ function readMisplacedFlagLength(args, index) {
     if (booleanFlag !== undefined) {
         return booleanFlag === 'shouldShowHelp' || booleanFlag === 'shouldShowVersion' ? undefined : 1;
     }
-    const styleArgument = readOutputStyleArgument(args, index);
-    return styleArgument?.ok === true ? styleArgument.consumedCount : undefined;
+    const valueArgument = readOutputStyleArgument(args, index) ?? readDelegateArgument(args, index);
+    return valueArgument?.ok === true ? valueArgument.consumedCount : undefined;
 }
 function splitMisplacedFlags(passthrough) {
     const flagNames = new Set();
@@ -1052,15 +1164,12 @@ function splitMisplacedFlags(passthrough) {
             index++;
             continue;
         }
-        flagNames.add(arg.startsWith(`${OUTPUT_STYLE_FLAG}=`) ? OUTPUT_STYLE_FLAG : arg);
+        flagNames.add(arg.split('=', 1)[0] ?? arg);
         movedTokens.push(...passthrough.slice(index, index + flagLength));
         index += flagLength;
     }
     return { flagNames: [...flagNames], movedTokens, remainingTokens };
 }
-function quoteForShell(arg) {
-    return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
-}
 function wrapWithHooks(command, mainSteps, registry, anchorDir, isWorkspaceRoot) {
     const steps = [];
     if (hasRunnableHook(`${command}:pre`, registry, anchorDir, isWorkspaceRoot)) {

package/dist/esm/verdict.d.ts

@@ -29,6 +29,8 @@ export type NoOpReason = 'empty-override' | 'empty-workspace' | 'noop-override';
  */
 export type Verdict = {
     command: string;
+    /** The host on which a delegated command ran, which a command that ran here does not have. */
+    host?: string;
     scope: string;
 } & VerdictOutcome;
 /**

package/dist/esm/verdict.js

@@ -23,13 +23,14 @@ const MIN_CUT_BYTES = Buffer.byteLength(TRUNCATION_MARK);
 const REPLAY_MARKER = 'replayed:';
 function describeOutcome(verdict, style) {
     const statuses = STATUS_GLYPHS[style];
+    const onHost = verdict.host === undefined ? '' : ` on ${verdict.host}`;
     switch (verdict.outcome) {
         case 'passed':
-            return { marker: statuses.passed.text, phrase: `passed in ${formatDuration(verdict.durationMs)}` };
+            return { marker: statuses.passed.text, phrase: `passed${onHost} in ${formatDuration(verdict.durationMs)}` };
         case 'failed':
             return {
                 marker: statuses.failed.text,
-                phrase: `failed in ${formatDuration(verdict.durationMs)} (exit ${verdict.exitCode})`,
+                phrase: `failed${onHost} in ${formatDuration(verdict.durationMs)} (exit ${verdict.exitCode})`,
             };
         case 'recalled': {
             const saving = formatSaving(verdict.savedMs);

package/dist/esm/vitest-source-resolution.js

@@ -135,10 +135,9 @@ function matchSubpath(exportsValue, subpath) {
             continue;
         const base = key.slice(0, star);
         const suffix = key.slice(star + 1);
-        if (!subpath.startsWith(base) || !subpath.endsWith(suffix))
-            continue;
-        if (subpath.length < base.length + suffix.length)
+        if (!subpath.startsWith(base) || !subpath.endsWith(suffix) || subpath.length < base.length + suffix.length) {
             continue;
+        }
         if (bestMatch !== undefined && bestMatch.base.length >= base.length)
             continue;
         bestMatch = { base, value, wildcard: subpath.slice(base.length, subpath.length - suffix.length) };

package/docs/check-cache.md

@@ -93,7 +93,7 @@ $ nmr check
 ⏩ nmr-core: check: passed 3m ago on this tree, saved ~48s — replayed: nmr-core: fmt:check: All matched files use Prettier code style!; nmr-core: test: Test Files 6 passed (6) Tests 41 passed (41)
 ```
 
-The assembly is flat: A constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A delegate expands into the scopes to which it fans out, and a constituent that did not record an excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all. `ci` replays what `check:strict` earned and nothing for `build`.
+The assembly is flat: A constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A fan-out expands into the scopes that it selects, and a constituent that did not record an excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all. `ci` replays what `check:strict` earned and nothing for `build`.
 
 Every excerpt in the assembly was certified during a single run, on a single tree, because nmr assembles it when the composite records its pass rather than when it skips. `NMR_RUN_ID` makes that provable; see [reserved environment variables](#reserved-environment-variables).
 
@@ -133,7 +133,7 @@ $ nmr --log test
 🟠 nmr: test: no recording; the last pass was 3m ago, on a tree that this is not
 ```
 
-**`--log` applies to the scopes that `-F` and `-R` select.** nmr passes the flag to the delegate. Each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: Partial coverage is normal for a survey, and failing on the first gap would hide every scope that had something to show. A selection that does not include any scope is the other case and fails, as it does for a run: An empty selection is not a partial survey.
+**`--log` applies to the scopes that `-F` and `-R` select.** nmr passes the flag to each scope that it selects. Each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: Partial coverage is normal for a survey, and failing on the first gap would hide every scope that had something to show. A selection that does not include any scope is the other case and fails, as it does for a run: An empty selection is not a partial survey.
 
 **Retention has a ceiling of 256 KiB per recorded pass**, distinct from the 512 bytes to which a verdict line is held. nmr keeps 128 KiB from each end of a transcript that overruns it, because a run's opening and its closing statement each contain what the other does not, and it marks the drop with a line that names the dropped bytes, rather than cutting silently.
 

package/docs/delegate.md

@@ -0,0 +1,61 @@
+# Delegating to another machine
+
+nmr runs a command on another machine over SSH, against the working tree on this one, and reports the command's output and exit status here:
+
+```console
+$ nmr --delegate imac2 ci
+# ... the host's own output and verdicts ...
+✅ my-repo: ci: passed on imac2 in 1m 48s
+```
+
+A machine that runs several worktrees' checks at once runs out of memory, and the [machine lock](machine-lock.md) protects it by making the checks wait for one another. Delegation moves a check to a machine that has the room for it instead.
+
+## Choosing where a command runs
+
+| Step                          | Effect                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `nmr --delegate <host> <cmd>` | Runs the command on `<host>`. `--delegate=<host>` is the same.          |
+| `NMR_DELEGATE=<host>`         | Runs every command that can be delegated on `<host>`.                   |
+| `nmr --no-delegate <cmd>`     | Runs the command here, whatever `NMR_DELEGATE` names. It outranks both. |
+
+`<host>` is anything that `ssh` accepts: a name from `~/.ssh/config`, `user@host`, or an address. Like every nmr flag, these belong before the command name; nmr warns about one written after it, because the command then runs here.
+
+`NMR_DELEGATE` is how an agent session's checks reach the host without any change to the commands that the agent runs: Set it in the session's environment.
+
+## What can be delegated
+
+Every command whose contribution is its exit status: `ci`, `prepush`, `check`, the `test` commands, `typecheck`, and a custom script such as `test:e2e`. nmr decides on the name that the invocation gives, so `ci` runs on the host as one unit, `build` step included.
+
+These run here, and `--delegate` refuses them: `build`, `clean`, `compile`, `fix`, `fmt`, `lint`, `test:watch`, and `upgrade`, with their `root:` forms, which rewrite the working tree or run until stopped; and `--log`, which reads this machine's recordings. Under `NMR_DELEGATE`, they run here without comment.
+
+## What the host runs
+
+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. nmr does not remove these checkouts.
+
+- **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. `--delegate` refuses such a tree; under `NMR_DELEGATE`, the command runs here, and nmr prints one line saying why.
+- **One worktree delegates one command at a time.** Two delegations from the same worktree at once share a checkout on the host.
+
+On the host, the command runs under the host's own [machine lock](machine-lock.md) and [check-result cache](check-cache.md), so a host that serves several worktrees runs their heavy commands one at a time, and a tree that already passed there skips. A delegated run does not take the lock here, and it neither consults nor records this machine's cache, whose key is specific to the machine.
+
+Ctrl-C ends the run on the host as well as here.
+
+## Reporting
+
+The host's nmr prints its output and verdicts, and nmr here adds one verdict for the whole delegation, its transfer and install included, which names the host. `--json` adds a `host` field to that object; see [reporting for a machine](reporting.md#reporting-for-a-machine).
+
+A failure of the delegation itself, rather than of the command, exits 255, the status with which `ssh` reports its own failures, and names the step that failed, after what that step printed:
+
+```console
+❌ 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>`.
+
+## Setting up the host
+
+- **SSH that does not prompt.** nmr runs `ssh` with `BatchMode=yes`, so a key that needs a passphrase must be in the agent, and the host key must already be known. An unreachable host fails within 10 seconds.
+- **git, Node, and pnpm on the interactive login shell's `PATH`.** nmr reads `PATH` from the host's login shell started as an interactive one, which loads `~/.zshrc` or `~/.bashrc` as well as the login profile: That is where pnpm's installer and the common version managers put Node and pnpm. What the startup files print does not reach the output, but whatever else they do runs before each step. When pnpm is not on that `PATH`, the install step fails, naming `PATH`. The login shell must accept `-ilc`: bash and zsh do.
+- **A sandboxed agent session needs network access to the host.** A sandbox that allows only HTTP egress refuses `ssh`, and the delegation fails at `prepare`.

package/docs/machine-lock.md

@@ -17,9 +17,10 @@ The waiting line goes to stderr in every verbosity and report format. The time s
 - **`test:watch` does not take the lock.** It runs until it is stopped, and would block every other run for as long.
 - **A composite takes the lock when it reaches a heavy step.** `prepush` runs its audit unlocked, then waits, if it has to, before `ci`.
 - **A command nested in a heavy one runs under its hold.** The holder passes its token to the processes that it starts, so `ci` running `check:strict` running `test` takes the lock once.
-- **A fan-out takes the lock once.** `nmr -R test` and `nmr -F <pattern> test` hold it in the delegating process, so the packages that pnpm runs in parallel do not wait on one another.
+- **A fan-out takes the lock once.** `nmr -R test` and `nmr -F <pattern> test` hold it in the process that fans out, so the packages that pnpm runs in parallel do not wait on one another.
 - **A cached pass does not wait.** nmr consults the [check-result cache](check-cache.md) before it takes the lock, and a command that the cache serves never waits. A run that did wait consults the cache again, because the run that it waited on may have recorded a pass for the same tree.
 - **`--log` does not take the lock**, because it runs nothing.
+- **A [delegated](delegate.md) command takes the host's lock**, not this machine's.
 
 ## Where the lock lives
 

package/docs/reporting.md

@@ -29,7 +29,7 @@ $ nmr --json check
 {"command":"check","scope":"nmr-core","outcome":"passed","durationMs":31204}
 ```
 
-Every object contains `command`, `scope`, and `outcome`, and then the fields that only that outcome includes:
+Every object contains `command`, `scope`, and `outcome`, and then the fields that only that outcome includes. A [delegated](delegate.md) command's own verdict also contains `host`, the host on which it ran:
 
 | `outcome`  | Also contains                                                                                                           |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,7 +77,7 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.3",
+    "@williamthorsen/nmr-core": "0.13.4",
     "@williamthorsen/toolbelt.errors": "0.8.3",
     "@williamthorsen/toolbelt.filesystem": "0.9.3",
     "glob": "13.0.6",
@@ -90,10 +90,10 @@
     "@williamthorsen/toolbelt.testing": "0.6.3",
     "@williamthorsen/toolbelt.vitest": "0.10.3",
     "esbuild": "0.28.2",
-    "readyup": "0.40.0",
+    "readyup": "0.41.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.3",
+    "vite": "8.3.4",
     "vitest": "4.1.11",
     "yaml": "2.9.1"
   },