@williamthorsen/nmr 0.47.0 → 0.49.0

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.49.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"
@@ -30,6 +75,16 @@
           "kind": "module",
           "path": "../../nmr-core/dist/esm/cache-store.js"
         },
+        {
+          "hash": "81f1406b",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/collectChangedPaths.js"
+        },
+        {
+          "hash": "200f69f1",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/gitObjects.js"
+        },
         {
           "hash": "54384dca",
           "kind": "module",
@@ -41,7 +96,7 @@
           "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
         },
         {
-          "hash": "211453c6",
+          "hash": "1eb2b90c",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
         },
@@ -56,10 +111,15 @@
           "path": "../../nmr-core/dist/esm/index.js"
         },
         {
-          "hash": "2507870d",
+          "hash": "89d3e3b4",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/parseArgs.js"
         },
+        {
+          "hash": "7915ba49",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/runGit.js"
+        },
         {
           "hash": "14547f78",
           "kind": "module",
@@ -81,12 +141,67 @@
           "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
         },
         {
-          "hash": "aaeb1a84",
+          "hash": "9fd61bf4",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "a06b470a",
+          "hash": "fbdddbc3",
+          "kind": "module",
+          "path": "lib/bin-targets.ts"
+        },
+        {
+          "hash": "56e92527",
+          "kind": "module",
+          "path": "lib/catalog.ts"
+        },
+        {
+          "hash": "369c92bb",
+          "kind": "module",
+          "path": "lib/github.ts"
+        },
+        {
+          "hash": "4f0d7859",
+          "kind": "module",
+          "path": "lib/manifest-fields.ts"
+        },
+        {
+          "hash": "e3de73f8",
+          "kind": "module",
+          "path": "lib/repo-files.ts"
+        },
+        {
+          "hash": "2a90a1d3",
+          "kind": "module",
+          "path": "lib/root-scripts.ts"
+        },
+        {
+          "hash": "3d661ab8",
+          "kind": "module",
+          "path": "lib/self-hosted-runner.ts"
+        },
+        {
+          "hash": "f8f79929",
+          "kind": "module",
+          "path": "lib/setup.ts"
+        },
+        {
+          "hash": "400757e6",
+          "kind": "module",
+          "path": "lib/shared-configs.ts"
+        },
+        {
+          "hash": "b3bdf8ee",
+          "kind": "module",
+          "path": "lib/vitest.ts"
+        },
+        {
+          "hash": "00130733",
+          "kind": "module",
+          "path": "lib/workspace-build.ts"
+        },
+        {
+          "hash": "08c09ade",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -94,12 +209,22 @@
           ]
         },
         {
-          "hash": "7e066d18",
+          "hash": "19b57f2e",
+          "kind": "module",
+          "path": "../src/config-check-cache.ts"
+        },
+        {
+          "hash": "2cfe8c2e",
+          "kind": "module",
+          "path": "../src/config-validation.ts"
+        },
+        {
+          "hash": "5b589c7e",
           "kind": "module",
           "path": "../src/config.ts"
         },
         {
-          "hash": "0fb883a1",
+          "hash": "d2448f72",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
@@ -119,7 +244,7 @@
           "path": "../src/helpers/escapeControlCharacters.ts"
         },
         {
-          "hash": "47249ca4",
+          "hash": "2d1cf397",
           "kind": "module",
           "path": "../src/helpers/findClosestName.ts"
         },
@@ -154,7 +279,12 @@
           "path": "../src/resolver.ts"
         },
         {
-          "hash": "ed585ab6",
+          "hash": "bb18a285",
+          "kind": "module",
+          "path": "../src/shell-syntax.ts"
+        },
+        {
+          "hash": "a1b70d65",
           "kind": "module",
           "path": "../src/steps.ts"
         },
@@ -169,7 +299,7 @@
           "path": "../src/UserError.ts"
         },
         {
-          "hash": "857c630c",
+          "hash": "ecf8a873",
           "kind": "module",
           "path": "../src/verbosity.ts"
         },
@@ -186,10 +316,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.40.0",
+      "readyupVersion": "0.42.0",
       "source": "kits/default.ts",
-      "sourceHash": "aaeb1a84",
-      "targetHash": "125a39cc"
+      "sourceHash": "9fd61bf4",
+      "targetHash": "b0939edd"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.49.0 — 2026-10-18
+
+### 🎉 Features
+
+- Makes a delegation wait while another delegation from the same worktree holds the host checkout, printing `nmr: waiting for <command> in <dir> (pid <pid>) to finish on <host>` and leaving the wait out of the verdict's duration. (#1079)
+- Extends Ctrl-C, which previously ended only the run step on the host, to end the delegation during the wait for the checkout, the check-out step, and the install step as well. (#1079)
+- Makes `nmr --delegate` fail at the check-out step with `could not check out on <host>: node is not on the PATH that the interactive login shell sets there` when the host's interactive login shell does not put Node on `PATH`, and documents that Node on the host must satisfy nmr's `engines` range (`>=24.16.0`). (#1079)
+- Makes `nmr --delegate` and `NMR_DELEGATE` look up this machine's check-result cache before contacting the host, so that a tree with a pass recorded here is reported as `passed … ago on this tree` and an unknown command is reported here, without either one reaching the host. (#1080)
+- Adds a record in this machine's check-result cache for each pass that a delegation host reports, so that a later delegation to the same host recalls it as `passed … ago on <host>` and `nmr --log` prints the host's transcript under a header that names the host. (#1080)
+- Makes `nmr --delegate` record the passes that the host reports for a delegated composite's constituents, so that `nmr --delegate <host> check` after `nmr --delegate <host> ci` on the same tree recalls the pass without contacting the host. (#1082)
+- Makes `nmr --delegate` record the excerpts that the host reports with each delegated pass, so that a recall of a delegated command, such as `ci`, replays them instead of nothing. (#1082)
+- Lets `--delegate` and `NMR_DELEGATE` take a comma-separated list of hosts in order of preference, from which nmr chooses the first host on which the delegation would not wait for a lock, otherwise the first host that answered nmr's lock check, and never the delegating machine. (#1083)
+- Extends the check-result cache to recall a pass earned on any host in the list, without checking any host's locks. (#1083)
+- 🚨 **Breaking:** Makes `--delegate` a boolean flag, under which `nmr` runs the command on a host that `NMR_DELEGATE` or the user config names, and adds `--delegate-to <hosts>` to name the hosts for one run. (#1084)
+- Adds a machine-level user config, `~/.config/nmr/config.ts`, in which `delegate.hosts` names this machine's hosts in order of preference and `delegate.when` selects the runs that `nmr` delegates to them without a flag: runs from a coding agent (`'agent'`) or every run (`'always'`), except when `CI` is set and for a `-F` or `-R` invocation. (#1084)
+- Adds the repo config key `delegate`, whose only accepted value, `false`, makes `nmr` run every check on the machine that has the working tree, overriding `NMR_DELEGATE` and the user config but not a delegation flag. (#1084)
+- Adds a stderr line, printed by `nmr` when a delegation decided by the user config cannot reach a host, that names the config file and the remedies in order: network access to the hosts, then `nmr --no-delegate <command>`. (#1084)
+- Updates the `nmr` rulebook to direct agents not to pass `--delegate` or `--delegate-to`, since the user config decides delegation, and to ask for network access to a host before running `nmr --no-delegate`. (#1084)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the snapshot sent to the host by `nmr --delegate` omitted a file edited in the same second as git's last write of the index. (#1078)
+- Fixes the issue that `NMR_NO_CACHE`, `NMR_DEBUG`, and `NMR_RUN_ID` set on this machine did not reach the delegation host, which left the host's cache in use under `NMR_NO_CACHE=1`. (#1080)
+
+### ⚡ Performance
+
+- Keys the check cache on the git tree id that `git add --all` would record for the working tree, which lets `nmr` skip a check after the checked tree is committed, and invalidates every pass recorded by earlier versions once. (#1078)
+
+### ♻️ Refactoring
+
+- Splits the `nmr` source modules that exceeded the 300-line `max-lines` limit, such as `check-cache.ts` and `commands/build.ts`, into one module per concern, and moves each module's tests with its code. (#1061)
+- Splits `config.ts`, `steps.ts`, and the default readyup kit `.readyup/kits/default.ts` to bring each under the 300-line `max-lines` limit, moving field-shape validation into `config-validation.ts`, the `checkCache` name check into `config-check-cache.ts`, shell tokenizing and quoting into `shell-syntax.ts`, and each kit section into a module under `.readyup/lib/`. (#1063)
+- Moves the argument parser, the invocation types, pnpm fan-out, the delegate host, chain assembly, hook wrapping, crossing diagnostics, the check-cache gate and its recording, the child environment, and presentation out of `runCli.ts` into modules of their own, leaving `runCli.ts` with the run orchestration and bringing it under the 300-line `max-lines` limit. (#1064)
+- Rewrites the code that the new and widened rules in `eslint-plugin-unicorn` 78 report, mostly by changing `flatMap` callbacks to return a single value rather than a one-element array. (#1072)
+- Renames nmr's default Prettier config from `prettier-default-config.ts` to `prettier-default.config.ts`, so that the upstream exemption of tool-loaded `*.config.*` files from `unicorn/no-top-level-side-effects` covers it, and updates `nmr-fmt` to resolve the new name. (#1072)
+
+### 🧪 Tests
+
+- Splits the `nmr` test files that exceeded the 500-line `max-lines` limit for tests into files by aspect, and moves the fixtures and fake-spawn helpers that the new files share into `test-utils/`. (#1061)
+- Splits `runCli.unit.test.ts` into four files named for the aspect that each covers and moves the pre/post hooks suite out of `cli.tool.test.ts` into `cli.hooks.tool.test.ts`, with the workspace-tree factory, the in-process runners, and the bin harness moved into shared files under `test-utils/`. (#1064)
+
+## 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,33 @@
 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.49.0 (2026-10-18)
 
 ### 🎉 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)
+- Makes a delegation wait while another delegation from the same worktree holds the host checkout, printing `nmr: waiting for <command> in <dir> (pid <pid>) to finish on <host>` and leaving the wait out of the verdict's duration. (#1079)
+- Extends Ctrl-C, which previously ended only the run step on the host, to end the delegation during the wait for the checkout, the check-out step, and the install step as well. (#1079)
+- Makes `nmr --delegate` fail at the check-out step with `could not check out on <host>: node is not on the PATH that the interactive login shell sets there` when the host's interactive login shell does not put Node on `PATH`, and documents that Node on the host must satisfy nmr's `engines` range (`>=24.16.0`). (#1079)
+- Makes `nmr --delegate` and `NMR_DELEGATE` look up this machine's check-result cache before contacting the host, so that a tree with a pass recorded here is reported as `passed … ago on this tree` and an unknown command is reported here, without either one reaching the host. (#1080)
+- Adds a record in this machine's check-result cache for each pass that a delegation host reports, so that a later delegation to the same host recalls it as `passed … ago on <host>` and `nmr --log` prints the host's transcript under a header that names the host. (#1080)
+- Makes `nmr --delegate` record the passes that the host reports for a delegated composite's constituents, so that `nmr --delegate <host> check` after `nmr --delegate <host> ci` on the same tree recalls the pass without contacting the host. (#1082)
+- Makes `nmr --delegate` record the excerpts that the host reports with each delegated pass, so that a recall of a delegated command, such as `ci`, replays them instead of nothing. (#1082)
+- Lets `--delegate` and `NMR_DELEGATE` take a comma-separated list of hosts in order of preference, from which nmr chooses the first host on which the delegation would not wait for a lock, otherwise the first host that answered nmr's lock check, and never the delegating machine. (#1083)
+- Extends the check-result cache to recall a pass earned on any host in the list, without checking any host's locks. (#1083)
+- 🚨 **Breaking:** Makes `--delegate` a boolean flag, under which `nmr` runs the command on a host that `NMR_DELEGATE` or the user config names, and adds `--delegate-to <hosts>` to name the hosts for one run. (#1084)
+- Adds a machine-level user config, `~/.config/nmr/config.ts`, in which `delegate.hosts` names this machine's hosts in order of preference and `delegate.when` selects the runs that `nmr` delegates to them without a flag: runs from a coding agent (`'agent'`) or every run (`'always'`), except when `CI` is set and for a `-F` or `-R` invocation. (#1084)
+- Adds the repo config key `delegate`, whose only accepted value, `false`, makes `nmr` run every check on the machine that has the working tree, overriding `NMR_DELEGATE` and the user config but not a delegation flag. (#1084)
+- Adds a stderr line, printed by `nmr` when a delegation decided by the user config cannot reach a host, that names the config file and the remedies in order: network access to the hosts, then `nmr --no-delegate <command>`. (#1084)
+- Updates the `nmr` rulebook to direct agents not to pass `--delegate` or `--delegate-to`, since the user config decides delegation, and to ask for network access to a host before running `nmr --no-delegate`. (#1084)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the snapshot sent to the host by `nmr --delegate` omitted a file edited in the same second as git's last write of the index. (#1078)
+- Fixes the issue that `NMR_NO_CACHE`, `NMR_DEBUG`, and `NMR_RUN_ID` set on this machine did not reach the delegation host, which left the host's cache in use under `NMR_NO_CACHE=1`. (#1080)
+
+### ⚡ Performance
+
+- Keys the check cache on the git tree id that `git add --all` would record for the working tree, which lets `nmr` skip a check after the checked tree is committed, and invalidates every pass recorded by earlier versions once. (#1078)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -195,6 +213,25 @@ 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 runs a check on another machine over SSH, against this working tree, and exits with its status. A user config on each machine, `~/.config/nmr/config.ts`, names the hosts in order of preference, and with `when` delegates agents' runs, or every run, without being asked:
+
+```ts
+export default {
+  delegate: { hosts: ['imac2', 'imac3'], when: 'agent' },
+};
+```
+
+`--delegate-to` names the hosts for one run, and nmr runs on the first one that is not busy:
+
+```console
+$ nmr --delegate-to imac2 ci
+✅ my-repo: ci: passed on imac2 in 1m 48s
+```
+
+A delegation consults the [check-result cache](#check-result-cache) first, so a tree that already passed is not sent to the host; a pass that a host earned does not satisfy a run here. A repo whose checks must run on the machine that has the tree declares `delegate: false` in its config. [Delegating to another machine](docs/delegate.md) covers the user config, `--delegate`, `NMR_DELEGATE`, the rules that decide where a command runs, which commands can be delegated, how nmr chooses among several hosts, how the cache is consulted, what the host runs, how failures are reported, and setting up the host.
+
 ## Shared configs and helpers
 
 ### Shared Vitest config
@@ -299,6 +336,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): The user config, `--delegate`, `--delegate-to`, `NMR_DELEGATE`, where a command runs, choosing among several hosts, 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.
+- Delegation is configured per machine, in nmr's user config (`~/.config/nmr/config.ts`), so a command may run on another machine without being asked: Never pass `--delegate` or `--delegate-to`. A verdict reading `passed on <host>` or `failed on <host>` reports a command that ran on that machine; the output above it is the host's. A delegation consults this machine's check-result cache first: `passed … ago on this tree` recalls a pass earned here, and `passed … ago on <host>` one that the host earned, without contacting it. A failure that names the user config, or exit 255 with `could not prepare <host>` inside a sandbox, means that the sandbox refused `ssh`: Ask for network access to the host first, and run the command here with `nmr --no-delegate <command>` only when that is refused.
+- 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 the user config, the rules that decide where a command runs, which commands can run 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/check-cache-build-output.d.ts

@@ -0,0 +1,24 @@
+import type { NmrConfig } from './types.js';
+/** What nmr's own build has left on disk across the workspace. */
+export interface BuildOutputState {
+    /** Covered packages whose output is absent. */
+    missingPackages: string[];
+    /** The digest of the inputs from which each covered package's output was built, keyed by package name. */
+    digests: Record<string, string>;
+}
+/**
+ * Names a covered package whose output differs between two observations of it, or `undefined` when every
+ * package agrees. A package that has appeared or disappeared between them counts as a disagreement, because
+ * the output that the earlier observation describes is not the output that the later one found.
+ */
+export declare function findStaleBuildOutput(earlierDigests: Record<string, string>, laterDigests: Record<string, string>): string | undefined;
+/**
+ * Reads the state of the build output that nmr's own build covers. Build output is git-ignored, so the tree id
+ * says nothing about it: a `ci` whose `build` constituent is cached would otherwise skip on a tree whose `dist`
+ * had been deleted, or whose `dist` was compiled from a different tree, and hand back a green exit over a
+ * repository that cannot run.
+ *
+ * Because a package whose `build` or `compile` is overridden emits to a location that this function does not
+ * know about, it is left out rather than made a permanent miss.
+ */
+export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;

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

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { hasBuildOutput, readBuildDigest } from "./commands/build-output.js";
+import { loadWorkspaceConfig } from "./config.js";
+import { getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { renderChain } from "./steps.js";
+import { getWorkspacePackageDirs } from "./workspace.js";
+const BUILT_IN_COMPILE = 'nmr-compile';
+export function findStaleBuildOutput(earlierDigests, laterDigests) {
+    const names = [...new Set([...Object.keys(earlierDigests), ...Object.keys(laterDigests)])].toSorted();
+    return names.find((name) => earlierDigests[name] !== laterDigests[name]);
+}
+export async function readBuildOutputState(monorepoRoot, config) {
+    const state = { missingPackages: [], digests: {} };
+    let packageDirs;
+    try {
+        packageDirs = getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        return state;
+    }
+    const registry = buildWorkspaceRegistry(config);
+    if (JSON.stringify(registry['build']) !== JSON.stringify(getDefaultWorkspaceScripts()['build'])) {
+        return state;
+    }
+    for (const packageDir of packageDirs) {
+        if (!isProbeSubject(packageDir, registry)) {
+            continue;
+        }
+        const { build } = await loadWorkspaceConfig(packageDir);
+        const options = build?.extraIgnorePatterns === undefined ? {} : { extraIgnorePatterns: build.extraIgnorePatterns };
+        const name = path.relative(monorepoRoot, packageDir);
+        if (await hasBuildOutput(packageDir, options)) {
+            state.digests[name] = (await readBuildDigest(packageDir)) ?? '';
+        }
+        else {
+            state.missingPackages.push(name);
+        }
+    }
+    return state;
+}
+function isProbeSubject(packageDir, registry) {
+    const build = resolveScript('build', registry, packageDir, false);
+    if (build === undefined || build.origin.tier === 'package') {
+        return false;
+    }
+    const compile = resolveScript('compile', registry, packageDir, false);
+    return compile !== undefined && renderChain(compile.steps) === BUILT_IN_COMPILE;
+}

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

@@ -0,0 +1,27 @@
+import { type TreeSnapshot } from './check-cache.js';
+import type { BuildOutputState } from './check-cache-build-output.js';
+import type { HostRunResult } from './delegate-host.js';
+import { type RunPlan } from './invocation.js';
+import type { OutputChannels } from './output-channel.js';
+/** What the check-result cache gates a run on: the key, the tree, and the build output that the run saw. */
+export interface Gate {
+    buildOutputBefore: BuildOutputState;
+    /** The channels on which the invocation's output runs, which every retention key that it records folds. */
+    channels: OutputChannels;
+    key: string;
+    retentionKey: string;
+    snapshot: TreeSnapshot;
+}
+/**
+ * Records the passes that the host earned, provided that the tree pushed to it is the tree on which the gate keyed,
+ * and that the working tree did not move while the host ran: a pass over any other tree says nothing about this one.
+ *
+ * Each valid entry of the host's pass manifest is recorded as a pass that the host earned at the entry's scope. It is
+ * keyed on this machine's inputs and the host's command string, so that an entry whose string differs from what would
+ * run here is never recalled, and its excerpts are keyed on this invocation's presentation, for which the host styled
+ * them. The invocation's own entry supplies only the retention of the invocation's pass, which is recorded last, so
+ * that a reader never sees a composite's pass ahead of its constituents' passes.
+ */
+export declare function recordDelegatedPass(plan: RunPlan, gate: Gate, hostRun: Extract<HostRunResult, {
+    kind: 'ran';
+}>): Promise<void>;

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

@@ -0,0 +1,92 @@
+import path from 'node:path';
+import { resolveTreeSnapshot, writeDebugNote } from "./check-cache.js";
+import { computeCacheKey, computeRetentionKey } from "./check-cache-key.js";
+import { recordHostPass } from "./check-cache-record.js";
+import { VERSION } from "./invocation.js";
+import { formatManifestScope, validatePassManifest } from "./pass-manifest.js";
+export async function recordDelegatedPass(plan, gate, hostRun) {
+    const { anchorDir, command, context, env, stderr } = plan.invocation;
+    const { config, monorepoRoot } = context;
+    if (hostRun.treeId !== gate.snapshot.treeId) {
+        writeDebugNote(`not recording ${command}: the pushed tree is not the tree that the gate keyed on`, env, stderr);
+        return;
+    }
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    if (!currentRead.ok) {
+        writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
+        return;
+    }
+    if (currentRead.snapshot.treeId !== gate.snapshot.treeId) {
+        writeDebugNote(`not recording ${command}: the tree changed while it ran`, env, stderr);
+        return;
+    }
+    const entries = validatePassManifest({
+        checkCache: config.checkCache,
+        entries: hostRun.passes,
+        env,
+        monorepoRoot,
+        stderr,
+        treeId: gate.snapshot.treeId,
+        workspacePackageDirs: context.workspacePackageDirs,
+    });
+    const ownScope = formatManifestScope(monorepoRoot, anchorDir);
+    let ownReplay;
+    for (const entry of entries) {
+        if (entry.scope === ownScope && entry.command === command) {
+            if (entry.commandString === plan.commandString) {
+                ownReplay = entry.replay;
+            }
+            continue;
+        }
+        await recordLearnedPass(plan, gate, hostRun.host, entry);
+    }
+    await recordHostPass({
+        commandString: plan.commandString,
+        config,
+        durationMs: hostRun.durationMs,
+        env,
+        host: hostRun.host,
+        key: gate.key,
+        monorepoRoot,
+        ref: { anchorDir, command, monorepoRoot },
+        retainedOutput: hostRun.retainedOutput,
+        retention: composeRetention(gate.retentionKey, ownReplay, plan.runId),
+        snapshot: gate.snapshot,
+        stderr,
+    });
+}
+function composeRetention(key, replay, runId) {
+    return replay === undefined ? undefined : { key, replay, runId };
+}
+async function recordLearnedPass(plan, gate, host, entry) {
+    const { context, env, stderr } = plan.invocation;
+    const { monorepoRoot } = context;
+    const anchorDir = path.resolve(monorepoRoot, entry.scope);
+    const keyed = computeCacheKey({
+        anchorDir,
+        command: entry.command,
+        commandString: entry.commandString,
+        env,
+        monorepoRoot,
+        nmrVersion: VERSION,
+        snapshot: gate.snapshot,
+    });
+    if (!keyed.ok) {
+        writeDebugNote(`not recording ${entry.command} on ${host}: ${keyed.reason}`, env, stderr);
+        return;
+    }
+    await recordHostPass({
+        commandString: entry.commandString,
+        config: context.config,
+        durationMs: entry.durationMs,
+        env,
+        host,
+        key: keyed.key,
+        monorepoRoot,
+        ref: { anchorDir, command: entry.command, monorepoRoot },
+        retainedOutput: undefined,
+        retention: composeRetention(computeRetentionKey({ channels: gate.channels, env, passKey: keyed.key }), entry.replay, plan.runId),
+        snapshot: gate.snapshot,
+        stderr,
+    });
+}