@williamthorsen/nmr 0.48.0 → 0.49.0

package/dist/esm/verbosity.d.ts

@@ -23,6 +23,12 @@ export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
  * accepts a verbosity renders through this, the sources cannot come to name different ladders.
  */
 export declare function formatVerbosityRejection(source: string, value: string): string;
+/**
+ * Reports whether the environment contains a marker of a known agent harness. Keys on a variable's name and a
+ * non-empty value: The value convention belongs to the harness, so only a name-only rule keeps working when a
+ * harness changes it.
+ */
+export declare function hasAgentMarker(env: NodeJS.ProcessEnv, extraNames: readonly string[] | undefined): boolean;
 /** Narrows a raw value to a point on the loudness ladder. */
 export declare function isCommandVerbosity(value: string): value is CommandVerbosity;
 /**

package/dist/esm/verbosity.js

@@ -4,6 +4,13 @@ export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
 export function formatVerbosityRejection(source, value) {
     return `${source} is \`${value}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`;
 }
+export function hasAgentMarker(env, extraNames) {
+    const names = extraNames === undefined ? AGENT_ENV_VARS : [...AGENT_ENV_VARS, ...extraNames];
+    return names.some((name) => {
+        const value = env[name];
+        return value !== undefined && value !== '';
+    });
+}
 export function isCommandVerbosity(value) {
     const names = COMMAND_VERBOSITIES;
     return names.includes(value);
@@ -28,10 +35,3 @@ export function resolveVerbosity(options) {
         return output.commandVerbosity;
     return hasAgentMarker(env, output?.extraAgentEnvVars) ? 'quiet' : 'full';
 }
-function hasAgentMarker(env, extraNames) {
-    const names = extraNames === undefined ? AGENT_ENV_VARS : [...AGENT_ENV_VARS, ...extraNames];
-    return names.some((name) => {
-        const value = env[name];
-        return value !== undefined && value !== '';
-    });
-}

package/dist/esm/verdict.d.ts

@@ -1,6 +1,6 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-import type { ReplayLine } from './check-cache.js';
+import type { ReplayLine } from './check-cache-entries.js';
 import type { ReportFormat } from './report-format.js';
 /**
  * The ceiling to which a rendered verdict, its newline included, is held.

package/dist/esm/verdict.js

@@ -37,7 +37,7 @@ function describeOutcome(verdict, style) {
             const savingClause = saving === undefined ? '' : `, ${saving}`;
             return {
                 marker: statuses.skipped.text,
-                phrase: `passed ${formatDuration(verdict.ageMs)} ago on this tree${savingClause}`,
+                phrase: `passed ${formatDuration(verdict.ageMs)} ago on ${verdict.host ?? 'this tree'}${savingClause}`,
             };
         }
         case 'no-op':

package/docs/check-cache.md

@@ -33,41 +33,55 @@ Overriding a cacheable name, in `package.json` or in `workspaceScripts`, inherit
 
 A hit requires all of these to match the run that recorded the pass:
 
-- **The working tree's content**, hashed from the commit's tree object folded with the current content of every path that git reports as changed or untracked. Timestamps are not content, so a `touch` that does not rewrite any bytes leaves the hash alone.
+- **The working tree's content**, identified by the git tree id that `git add --all` would record for it, computed without writing to the repository. Timestamps are not content, so a `touch` that does not rewrite any bytes leaves the id alone; a mode change, such as `chmod +x`, moves it.
 - **The command string that would run**, hooks and all, and the scope in which it would run.
 - **nmr's version**, the **Node version**, and the **platform and architecture**.
 - **What pnpm has installed.** An install, a prune, or a lockfile change forces a re-run.
 - **`TZ`, `LANG`, `LC_ALL`, and `NODE_OPTIONS`.** This set is fixed, so two machines that differ only in other environment variables still agree.
 
-A hit additionally requires the build output of every package that nmr's own build covers to be present, and to have been built from this tree. Because output is git-ignored, neither its removal nor its replacement changes the hash: Restoring a tree with `git stash` or `git checkout` does not restore any of the output with which that tree was built. nmr compares each covered package's recorded build digest against the one on disk, and treats a `dist` compiled from another tree as a miss that the following run repairs. A package that overrides `build` or `compile` emits on terms that nmr does not know and is exempt.
+A hit additionally requires the build output of every package that nmr's own build covers to be present, and to have been built from this tree. Because output is git-ignored, neither its removal nor its replacement changes the tree id: Restoring a tree with `git stash` or `git checkout` does not restore any of the output with which that tree was built. nmr compares each covered package's recorded build digest against the one on disk, and treats a `dist` compiled from another tree as a miss that the following run repairs. A package that overrides `build` or `compile` emits on terms that nmr does not know and is exempt.
 
 A pass is recorded only when the command exits 0, only when the tree still matches the one against which the run started, only when every covered package's output is present and unchanged since the run started, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss). When output changes mid-run, whether another process rebuilt it or the chain built it itself, nmr cannot tell over which output the pass was earned: `nmr ci` is the one default command whose chain builds its own output, and it does not record a pass on a run whose build did work. The `nmr check:strict` inside that chain still records a pass, because it starts after the build.
 
 ## Out of contract
 
-These change what a check concludes without changing the hash. When one applies, exclude the affected command:
+These change what a check concludes without changing the tree id. When one applies, exclude the affected command:
 
-- **Content filters.** `core.autocrlf` and `.gitattributes` filters mean the bytes on disk differ from the bytes that git records; the hash follows what is on disk, but a checkout on another platform may not reproduce it.
-- **Symlinked inputs.** A symlink is hashed by the path that it names, not by the content of its target.
-- **Gitignored inputs.** Anything git does not report is invisible to the hash. The build-output probe is the one exception, and covers only nmr's own build.
+- **Content filters and git configuration.** The tree id follows `core.autocrlf` and `.gitattributes` filters as `git add` applies them, so it describes the bytes that git would record; a checkout on another platform may not reproduce the same normalized content. Configuration that changes what `git add` records, such as `core.fileMode=false` or `core.symlinks=false`, is not modeled: The id follows the mode and the link on disk.
+- **Symlinked inputs.** A symlink is identified by the path that it names, not by the content of its target.
+- **Gitignored inputs.** Anything git does not report is invisible to the tree id. The build-output probe is the one exception, and covers only nmr's own build.
 - **`passWithNoTests`.** A suite that does not collect any files exits 0, and that pass is recorded like any other.
 
-Committing an already-checked tree also changes the hash, because the commit's tree object is the base of the fold; the next run does the work again. The reverse holds and is useful: A rebase or an amended message that preserves content leaves the hash alone, as does checking out a branch whose tree is identical.
+Committing an already-checked tree keeps its tree id, so the next run skips. A rebase or an amended message that preserves content keeps it too, as does checking out a branch whose tree is identical.
 
 ## When the cache does not apply
 
 The gate never wrongly skips. When it cannot be sure, it does nothing and the command runs:
 
 - Outside a git repository, when git fails, or when `HEAD` does not resolve to a commit.
-- When the repository declares or contains submodules, whose content the hash does not cover.
+- When the repository declares or contains submodules, whose content the tree id does not cover.
 - When the monorepo root is not the git toplevel.
-- When a changed path cannot be read, or is neither a file nor a symlink (an untracked nested repository, for instance).
+- When a changed path cannot be read, contains a newline or bytes that are not UTF-8, or is neither a file nor a symlink (an untracked nested repository, for instance).
 - When the repository does not have a pnpm install to fingerprint.
-- Under a `devBin` substitution, which runs a binary built from a location that the hash does not describe.
+- Under a `devBin` substitution, which runs a binary built from a location that the tree id does not describe.
 - For any invocation carrying arguments after the command name, and for every step below it: the arguments narrow what runs, and a step served from a recorded pass is a step that did not.
 
 `NMR_DEBUG=1` reports why a run did not skip and why the cache did not apply.
 
+## Delegated passes
+
+A [delegated](delegate.md#consulting-the-cache-first) invocation consults this cache before it contacts the host, under the same key as a run here: The key describes the work as this machine sees it, and each entry also records which machine earned the pass.
+
+- **A pass earned here** satisfies a run here and a delegation to any host.
+- **A pass earned on a host** satisfies only a delegation whose list includes that host, and is not held to this machine's build output, which says nothing about the host's. Under a [user config](delegate.md#the-user-config) whose `when` delegates by default, a run that `--no-delegate` keeps here therefore re-runs a check that the host passed.
+- **The key contains this machine's Node version and install, not the host's.** A change on the host alone, such as a Node upgrade there, does not invalidate a pass recorded here. The host's own cache keys on its own.
+- **A host pass is recorded only when the tree pushed to the host is the tree on which the key was computed**, and it does not replace a pass earned here under the same key while that pass would still be recalled, its build output present and built from this tree.
+- **A host pass retains the transcript that the host sent back**, which `--log` prints under a header that names the host.
+- **A delegated composite records its constituents' passes too.** The host reports every pass that its nmr processes recorded or recalled during the run, and nmr records each one here as a pass earned on that host, at the scope where it ran. After `nmr --delegate-to imac2 ci`, `nmr --delegate-to imac2 check` on the same tree recalls without contacting the host, and a recall of `ci` replays its constituents' excerpts.
+- **A learned constituent is keyed on this machine's inputs and on the command string that the host ran**, so one whose string differs from what would run here is never recalled. Its excerpts are keyed on the [presentation environment](#replaying-a-skipped-runs-output) of the delegating invocation, for whose streams the host styled them. It does not retain a transcript, so `--log` prints its excerpts under the header that names the host.
+- **nmr treats the host's report as untrusted.** It drops an entry that is malformed, whose scope is not the root or one of its workspace packages, whose command is not cacheable here, or that describes another tree, and records the valid entries beside it. A delegation to a host whose nmr predates the report records the composite's pass alone, as before.
+- **A composite that the host recalled, and a `-F` or `-R` delegation, do not record any constituent's pass.** The first reports only its own entry; the second does not consult this machine's cache.
+
 ## Replaying a skipped run's output
 
 A skip reports an excerpt of the run that it recalls, marked as a recording rather than as this run's output:
@@ -154,9 +168,11 @@ Try these in order; the first is almost always the right one.
 
 ## Reserved environment variables
 
-`NMR_TREE_SNAPSHOT` is nmr's own: It passes one observation of the tree from a top-level invocation down to the processes that it spawns, so a chain hashes the tree once rather than at every link. nmr trusts an inherited value only while `HEAD` still points to the same commit as when the observation was taken, which bounds a process that outlives the run that spawned it. Because that bound does not extend to a tree edited without committing, **a process that survives its run and later invokes nmr should clear `NMR_TREE_SNAPSHOT`**. A test suite that shells out to `nmr` is the case worth checking.
+`NMR_TREE_SNAPSHOT` is nmr's own: It passes one observation of the tree from a top-level invocation down to the processes that it spawns, so a chain computes the tree id once rather than at every link. nmr trusts an inherited value only while `HEAD` still points to the same commit as when the observation was taken, which bounds a process that outlives the run that spawned it. Because that bound does not extend to a tree edited without committing, **a process that survives its run and later invokes nmr should clear `NMR_TREE_SNAPSHOT`**. A test suite that shells out to `nmr` is the case worth checking.
+
+`NMR_RUN_ID` is nmr's own too: It passes one run's identity from a top-level invocation down to the processes that it spawns, so that the excerpts recorded at every scope during one run are recognizable as that run's, and a composite can assemble from them. Whereas `NMR_TREE_SNAPSHOT` is bounded by `HEAD`, this one is bounded by the tree id that each entry records. A process that outlives its run and carries the identity into a later one contributes nothing to that run's assemblies.
 
-`NMR_RUN_ID` is nmr's own too: It passes one run's identity from a top-level invocation down to the processes that it spawns, so that the excerpts recorded at every scope during one run are recognizable as that run's, and a composite can assemble from them. Whereas `NMR_TREE_SNAPSHOT` is bounded by `HEAD`, this one is bounded by the tree hash that each entry records. A process that outlives its run and carries the identity into a later one contributes nothing to that run's assemblies.
+`NMR_PASS_MANIFEST_DIR` is nmr's own as well, and only the [host session](delegate.md#what-the-host-runs) sets it: It names the directory into which every nmr process of a delegated run reports the passes that it records or recalls, so that the delegating machine can [record the constituents](#delegated-passes) of a delegated composite. nmr does not forward it from this machine to the host.
 
 ## Configuring
 

package/docs/delegate.md

@@ -3,30 +3,96 @@
 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
+$ nmr --delegate-to 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.
+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. Which hosts a machine can reach is a fact about the machine, so a user config on the machine, not the repo, names them and turns delegation on.
+
+## The user config
+
+`~/.config/nmr/config.ts`, or `$XDG_CONFIG_HOME/nmr/config.ts` when `XDG_CONFIG_HOME` is set, declares this machine's hosts and when to delegate to them without being asked. It honors one key, `delegate`:
+
+```ts
+export default {
+  delegate: { hosts: ['imac2', 'imac3'], when: 'agent' },
+};
+```
+
+- **`hosts`** lists the hosts in order of preference. It is required whenever `delegate` is present.
+- **`when`** turns on delegation by default: `'agent'` for every run whose environment contains an agent-harness marker, the variables that also select [quiet output](reporting.md#configuring), extended by the repo's `output.extraAgentEnvVars`; `'always'` for every run. Without `when`, nmr delegates only on request, and `hosts` serves `--delegate`.
+
+nmr reads the file only when a decision reaches it, and an unrecognized key, a malformed `hosts`, or an unknown `when` fails that run with an error naming the file and the key. The file cannot import anything from a repo, so it is a plain object rather than a `defineConfig` call. When a directory above it contains a `package.json` without `"type"`, such as a stray `~/package.json`, Node warns on every load that the file's module type is not specified; a `~/.config/nmr/package.json` containing `{ "type": "module" }` silences it.
+
+A pass that a host earns satisfies a later delegation to that host, but not a run here: Under `when`, a run that `--no-delegate` keeps here re-runs a check that the host already passed. See [consulting the cache first](#consulting-the-cache-first).
 
 ## 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. |
+| Form                                 | Effect                                                                                                             |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `nmr --delegate <cmd>`               | Runs the command on `NMR_DELEGATE`'s hosts if it names any, otherwise the user config's; refused when neither does |
+| `nmr --delegate-to <hosts> <cmd>`    | Runs the command on `<hosts>`. `--delegate-to=<hosts>` is the same.                                                |
+| `nmr --no-delegate <cmd>`            | Runs the command here                                                                                              |
+| `NMR_DELEGATE=<hosts>`               | Runs every command that can be delegated on `<hosts>`                                                              |
+| `delegate: false` in the repo config | Keeps every command here unless a flag asks otherwise                                                              |
+
+`<hosts>` is one host or a comma-separated list in order of preference, such as `imac2,imac3`; see [choosing among several hosts](#choosing-among-several-hosts). A 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. `--delegate=<hosts>` is refused with a message naming `--delegate-to`, and so is a host name written after `--delegate`, which nmr reads as the command.
+
+The first rule that applies decides where a command runs:
+
+| #   | Condition                                                                               | Runs                                                                                                               |
+| --- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 1   | `--no-delegate`                                                                         | Here                                                                                                               |
+| 2   | `--delegate` or `--delegate-to`                                                         | On a host; a command that cannot be delegated, or a tree that cannot be snapshotted, is refused                    |
+| 3   | The repo config declares `delegate: false`                                              | Here                                                                                                               |
+| 4   | `NMR_DELEGATE` names hosts                                                              | On a host; a command that cannot be delegated runs here, and a tree that cannot be snapshotted, here with one line |
+| 5   | `NMR_DELEGATE` is set but does not name a host                                          | Here                                                                                                               |
+| 6   | The user config's `when` matches, `CI` is unset, and the invocation is not `-F` or `-R` | On a host, as for rule 4                                                                                           |
+| 7   | Otherwise                                                                               | Here                                                                                                               |
+
+- **A step and a `-F` or `-R` child run where their parent runs.** nmr gives every process that it starts an empty `NMR_DELEGATE`, which rule 5 reads as "here"; the run on a host already passes `--no-delegate`, so a host does not apply its own user config. A git hook that an agent's command starts is an agent run.
+- **A repo whose checks must run on the machine that has the tree** declares `delegate: false` in `.config/nmr.config.ts`, the only value that the repo config accepts for the key. It outranks `NMR_DELEGATE` and the user config, but not a flag.
+- **`NMR_DEBUG=1` names what sent a command to a host**, such as `delegating ci per ~/.config/nmr/config.ts (when: agent)`, `per NMR_DELEGATE`, or `per --delegate-to`.
+
+### Choosing among several hosts
+
+With several hosts, nmr asks every host at once, with one `ssh` call each, whether a delegation started now would wait there: whether the host's [machine lock](machine-lock.md), or the lock on this worktree's checkout there, has a live holder. A lock that its holder left behind does not count. nmr then runs on the first host in the list that is free; when none is, on the first host that answered; and when none answered, on the first host, where the delegation fails at `prepare`. It never runs the command here, because the machine that delegates is the one that delegation protects.
+
+```console
+$ NMR_DELEGATE=imac2,imac3 nmr ci
+✅ my-repo: ci: passed on imac3 in 1m 52s
+```
 
-`<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.
+- **A single host is not asked.** The delegation goes to it directly.
+- **The choice is advisory.** Two delegations that ask at the same moment can choose the same host, and then run one after the other under its locks.
+- **`NMR_DEBUG=1` shows the answers**, one line per host, such as `imac2 is busy`.
+- Whitespace, empty entries, and repeated hosts in the list are ignored; a `--delegate-to` value that does not name any host is refused.
 
-`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.
+The user config's `when: 'agent'` is how an agent session's checks reach the host without any change to the commands that the agent runs.
 
 ## 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.
+These run here, and `--delegate` and `--delegate-to` refuse 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` or the user config, they run here without comment.
+
+## Consulting the cache first
+
+nmr plans the command here and consults this machine's [check-result cache](check-cache.md#delegated-passes) before it contacts the host. When a recorded pass covers the tree, nmr reports the recall and does not reach the host:
+
+```console
+$ nmr --delegate-to imac2 ci
+⏩ my-repo: ci: passed 4m ago on this tree, saved ~1m 48s
+```
+
+- **A pass earned here satisfies a delegation** to any host.
+- **A pass earned on a host is recorded here** with that host, and a later delegation whose list includes that host recalls it as `passed 4m ago on imac2`, without asking any host whether it is free. A run here, or a delegation to other hosts, does not recall it. `nmr --log <command>` prints the output that the host sent back, under a header that names the host.
+- **A delegated composite records its constituents' passes too**, as the host reports them, so `nmr --delegate-to imac2 check` after `nmr --delegate-to imac2 ci` recalls without contacting the host, and a recall of `ci` replays its constituents' excerpts. A composite that the host itself recalled records only its own pass, and a `-F` or `-R` delegation does not record any pass; [delegated passes](check-cache.md#delegated-passes) has the rules.
+- **Only a miss reaches the host**, and it does not take the [machine lock](machine-lock.md) here.
+- **`--no-cache` and `NMR_NO_CACHE=1` skip the lookup** and reach the host, where they bypass its cache too.
+- **An invocation that nmr settles while planning**, such as an unknown command or an empty override, settles here without contacting the host.
+- **A `-F` or `-R` invocation is sent whole**, without consulting this machine's cache, and the host fans it out.
 
 ## What the host runs
 
@@ -35,12 +101,20 @@ nmr records the working tree as it is on disk as a commit: tracked changes, stag
 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.
+- **A repository with submodules cannot be delegated**, nor can a tree containing a nested repository, because the snapshot does not include their content. A delegation flag refuses such a tree; under `NMR_DELEGATE` or the user config, the command runs here, and nmr prints one line saying why.
 
-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.
+Delegations from the same worktree share its checkout on the host, so they run one at a time. A delegation that starts while another holds the checkout waits for it, saying so on stderr, then runs:
 
-Ctrl-C ends the run on the host as well as here.
+```console
+$ nmr --delegate-to imac2 test
+nmr: waiting for ci in /Users/me/repos/my-repo (pid 41872) to finish on imac2
+```
+
+The pid is that of the other delegation's nmr on this machine. The lock is the file `.git/nmr-delegate.lock` in the checkout, and it covers the checkout, the install, and the run, but not the push, which only transfers the snapshot. As with the machine lock, the time spent waiting does not count in the verdict's duration, and a lock left behind by an interrupted delegation is reclaimed by the next: at once when its holder's process on the host no longer exists, and otherwise once the holder has stopped refreshing the file for a minute. Delegations from different worktrees use different checkouts and do not wait for one another.
+
+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. The host's nmr receives nmr's own flags as they were given, and the variables that decide how it reports (`NMR_COMMAND_VERBOSITY`, `NMR_OUTPUT_STYLE`, and `NMR_REPORT_FORMAT`), whether it bypasses its cache (`NMR_NO_CACHE`), whether it writes debug notes (`NMR_DEBUG`), and which run it belongs to (`NMR_RUN_ID`). An `NMR_NO_LOCK` set here does not reach the host, while `--no-lock` does. The host session sets one variable itself, `NMR_PASS_MANIFEST_DIR`, naming a directory under the checkout's `.git/` into which the host's nmr processes report their passes; the session returns those reports here when the run ends and then removes the directory.
+
+Ctrl-C ends the delegation on the host as well as here, in every step, including the wait for the checkout.
 
 ## Reporting
 
@@ -54,8 +128,14 @@ A failure of the delegation itself, rather than of the command, exits 255, the s
 
 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>`.
 
+A delegation does not fall back to running here when it cannot reach a host. When the user config decided it and it fails at `prepare`, which is also where it fails when no host answered the probe, nmr adds a line naming the file and the remedies in order:
+
+```console
+nmr: ~/.config/nmr/config.ts sent ci to imac2, imac3; ask for network access to imac2, imac3, or run it here with nmr --no-delegate ci
+```
+
 ## 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`.
+- **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. Node on the host must satisfy nmr's own `engines` range (`>=24.16.0`). When Node is not on that `PATH`, the check-out step fails, and when pnpm is not, the install step fails; each failure names `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`. Under `when: 'agent'`, every check that the session runs fails this way until the session has that access.

package/docs/reporting.md

@@ -29,7 +29,12 @@ $ 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. A [delegated](delegate.md) command's own verdict also contains `host`, the host on which it ran:
+```console
+$ nmr --json --delegate-to imac2 typecheck
+{"command":"typecheck","host":"imac2","scope":"nmr-core","outcome":"recalled","ageMs":240000,"savedMs":18450}
+```
+
+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, and so does the recall of a pass that a host earned, whose prose line reads `passed 4m ago on <host>` in place of `on this tree`:
 
 | `outcome`  | Also contains                                                                                                           |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------- |

package/docs/scripts.md

@@ -122,6 +122,7 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 | ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `build`            | `{ extraIgnorePatterns?: string[] }`                                          | Patterns added to the build's ignore set (package config only)                                                                                                                                                                                                                                                                               |
 | `checkCache`       | `{ enabled?: boolean; extraCommands?: string[]; excludeCommands?: string[] }` | Which commands the [check-result cache](check-cache.md#check-result-cache) may skip                                                                                                                                                                                                                                                          |
+| `delegate`         | `false`                                                                       | Keeps every check on the machine that has the tree, whatever `NMR_DELEGATE` or the [user config](delegate.md#the-user-config) says; a delegation flag still sends a run elsewhere (root config only)                                                                                                                                         |
 | `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                                                                                                                                                                                                                                                                               |
 | `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                                                                                                                                                                                                                                                                                    |
 | `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                                                                                                                                                                                                                                                                                         |
@@ -130,7 +131,7 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 
 All fields are optional. [Script values](#script-values) describes `ScriptValue` and its step form, and both types are exported from `@williamthorsen/nmr/config`.
 
-Each field belongs to exactly one tier, and nmr loads from a config only the fields that its tier honors: `build` in a package config, the other five in the monorepo-root config. Declaring a field at the wrong tier fails with a message naming it and where it goes, as does a key that nmr does not recognize at all: A typo cannot degrade into a setting that silently applies nowhere.
+Each field belongs to exactly one tier, and nmr loads from a config only the fields that its tier honors: `build` in a package config, every other field in the monorepo-root config. Declaring a field at the wrong tier fails with a message naming it and where it goes, as does a key that nmr does not recognize at all: A typo cannot degrade into a setting that silently applies nowhere.
 
 ### Package-level configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -81,7 +81,7 @@
     "@williamthorsen/toolbelt.errors": "0.8.3",
     "@williamthorsen/toolbelt.filesystem": "0.9.3",
     "glob": "13.0.6",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
     "taze": "21.3.0",
     "unconfig": "7.5.0"
@@ -90,7 +90,7 @@
     "@williamthorsen/toolbelt.testing": "0.6.3",
     "@williamthorsen/toolbelt.vitest": "0.10.3",
     "esbuild": "0.28.2",
-    "readyup": "0.41.0",
+    "readyup": "0.42.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
     "vite": "8.3.4",