@williamthorsen/nmr 0.49.0 → 0.50.0

package/.meta/changelog.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "0.50.0",
+    "date": "2026-10-21",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Makes `nmr` run a command on this machine, after printing `nmr: running <command> here rather than on <hosts>` and what `ssh` reported, when the user config's `when` sends the command to other hosts and `ssh` cannot connect to any of them; until now, the delegation failed with exit 255 and a line that named `~/.config/nmr/config.ts`. (#1090)",
+            "hash": "07d3b1775a7d1353c3fdf2249970c11214e6a5af",
+            "entry": 1
+          },
+          {
+            "description": "Makes `nmr` delegate to a host that `ssh` connected to, rather than to the first listed host, when several delegation hosts are configured and the lock probe finds every one of them neither free nor busy. (#1090)",
+            "hash": "07d3b1775a7d1353c3fdf2249970c11214e6a5af",
+            "entry": 2
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that delegation ignored the environment's `GIT_SSH_COMMAND`: `nmr` replaced it with plain `ssh` for the push and ran plain `ssh` for every other call to the host, which kept a machine that reaches its hosts through an ssh wrapper or proxy, such as the Claude Code sandbox, from delegating. (#1088)",
+            "hash": "76f6fc6f3501848422196d551393e29813527ae8",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "📚 Documentation",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Documents in `docs/delegate.md` and the nmr rulebook that a sandboxed session must admit the host's `HostName` on port 22, as `ssh -G <host>` prints it, rather than its `~/.ssh/config` alias. (#1088)",
+            "hash": "76f6fc6f3501848422196d551393e29813527ae8",
+            "entry": 2
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.49.0",
     "date": "2026-10-18",
@@ -94,6 +138,11 @@
             "description": "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)",
             "hash": "ab09b251d5f0d641264b17e458cab60245596e08",
             "entry": 3
+          },
+          {
+            "description": "Make release-kit's readyup manifest independent of the compile directory (#1081)",
+            "body": "Fixes the issue that the manifest of release-kit's `npm-auto-publish` kit listed whichever workspaces `rdy compile` found in its working directory, so a rebuild from another directory changed it and the published copy named this repository's packages. Moves the construction of the kit's per-package rows to `rdy run` and raises the kit's `minReadyupVersion` to 0.42.0, the first readyup release that can build checks at run time.",
+            "hash": "bea0d66f5b804bf51259fa094a890af80917abca"
           }
         ]
       },
@@ -359,6 +408,17 @@
           }
         ]
       },
+      {
+        "title": "🏗️ Internal features",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Resolve package roots past dual-format marker manifests (#1016)",
+            "body": "Replaces nmr-core's hand-written package-root and version lookups with `findPackageRoot` and `resolveSelfVersion` re-exported from `@williamthorsen/toolbelt.packaging`, which pass over the `{\"type\": \"commonjs\"}` marker manifest of a dual-format layout to reach the package that declares a `name`. `nmr`, `release-kit`, and `v11y-check` switch from `readPackageVersion` to `resolveSelfVersion`, and the boundary guard now holds `toolbelt.packaging`, like `toolbelt.terminal`, to a single importer and a single declarer in nmr-core.",
+            "hash": "ff6627180d9e86d083656afb2c09a3fb190fc79d"
+          }
+        ]
+      },
       {
         "title": "♻️ Refactoring",
         "audience": "dev",

package/.readyup/kits/default.js

@@ -9184,7 +9184,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.49.0" };
+  const pickedFields = { "version": "0.50.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -24,7 +24,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 0.49.0",
+            "@williamthorsen/nmr >= 0.50.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -201,7 +201,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "08c09ade",
+          "hash": "4f47ba73",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -319,7 +319,7 @@
       "readyupVersion": "0.42.0",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "b0939edd"
+      "targetHash": "81b3206d"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.50.0 — 2026-10-21
+
+### 🎉 Features
+
+- Makes `nmr` run a command on this machine, after printing `nmr: running <command> here rather than on <hosts>` and what `ssh` reported, when the user config's `when` sends the command to other hosts and `ssh` cannot connect to any of them; until now, the delegation failed with exit 255 and a line that named `~/.config/nmr/config.ts`. (#1090)
+- Makes `nmr` delegate to a host that `ssh` connected to, rather than to the first listed host, when several delegation hosts are configured and the lock probe finds every one of them neither free nor busy. (#1090)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that delegation ignored the environment's `GIT_SSH_COMMAND`: `nmr` replaced it with plain `ssh` for the push and ran plain `ssh` for every other call to the host, which kept a machine that reaches its hosts through an ssh wrapper or proxy, such as the Claude Code sandbox, from delegating. (#1088)
+
+### 📚 Documentation
+
+- Documents in `docs/delegate.md` and the nmr rulebook that a sandboxed session must admit the host's `HostName` on port 22, as `ssh -G <host>` prints it, rather than its `~/.ssh/config` alias. (#1088)
+
 ## 0.49.0 — 2026-10-18
 
 ### 🎉 Features
@@ -25,6 +40,9 @@ All notable changes to this project will be documented in this file.
 
 - 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)
+- Make release-kit's readyup manifest independent of the compile directory (#1081)
+
+  Fixes the issue that the manifest of release-kit's `npm-auto-publish` kit listed whichever workspaces `rdy compile` found in its working directory, so a rebuild from another directory changed it and the published copy named this repository's packages. Moves the construction of the kit's per-package rows to `rdy run` and raises the kit's `minReadyupVersion` to 0.42.0, the first readyup release that can build checks at run time.
 
 ### ⚡ Performance
 
@@ -103,6 +121,12 @@ All notable changes to this project will be documented in this file.
 - Fixes the issue that the test-tier definitions in `vitest.md` gave a test that starts its own loopback server three defensible tiers: `tool` is now a process that the test starts or a program that the environment supplies, `localhost` a service already running on this machine, and an in-process server from the package's own dependency closure `unit`. (#1023)
 - Fixes the issue that `nmr`'s warning about a `package.json` script that runs `nmr` through a shell sent an entry whose whole value is `nmr <name>` to `.config/nmr.config.ts`, when the accurate edit is to replace that value with the command of the `<name>` script in the same file. (#1030)
 
+### 🏗️ Internal features
+
+- Resolve package roots past dual-format marker manifests (#1016)
+
+  Replaces nmr-core's hand-written package-root and version lookups with `findPackageRoot` and `resolveSelfVersion` re-exported from `@williamthorsen/toolbelt.packaging`, which pass over the `{"type": "commonjs"}` marker manifest of a dual-format layout to reach the package that declares a `name`. `nmr`, `release-kit`, and `v11y-check` switch from `readPackageVersion` to `resolveSelfVersion`, and the boundary guard now holds `toolbelt.packaging`, like `toolbelt.terminal`, to a single importer and a single declarer in nmr-core.
+
 ### ♻️ Refactoring
 
 - Moves the work of `runInvocation` in `nmr` into the phase functions `establishInvocation`, `planRun`, and `executePlan`, which `runCli` calls in order, and changes `runGated` and `reportRecording` to take a named `RunPlan` in place of an options object that repeated its fields. (#1014)

package/README.md

@@ -5,33 +5,16 @@
 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.49.0 (2026-10-18)
+## Release notes — v0.50.0 (2026-10-21)
 
 ### 🎉 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)
+- Makes `nmr` run a command on this machine, after printing `nmr: running <command> here rather than on <hosts>` and what `ssh` reported, when the user config's `when` sends the command to other hosts and `ssh` cannot connect to any of them; until now, the delegation failed with exit 255 and a line that named `~/.config/nmr/config.ts`. (#1090)
+- Makes `nmr` delegate to a host that `ssh` connected to, rather than to the first listed host, when several delegation hosts are configured and the lock probe finds every one of them neither free nor busy. (#1090)
 
 ### 🐛 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)
+- Fixes the issue that delegation ignored the environment's `GIT_SSH_COMMAND`: `nmr` replaced it with plain `ssh` for the push and ran plain `ssh` for every other call to the host, which kept a machine that reaches its hosts through an ssh wrapper or proxy, such as the Claude Code sandbox, from delegating. (#1088)
 <!-- /section:release-notes -->
 
 ## Installation

package/agents/guidance/rulebooks/nmr.md

@@ -15,5 +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.
-- 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.
+- 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 line reading `nmr: running <command> here rather than on <hosts>` reports that `ssh` reached none of the hosts and that the command ran here, so its verdict stands. The line ends with what `ssh` reported: A `sandbox proxy` message means that the sandbox refused `ssh`, and only then does network access to the host's `HostName` on port 22, the name that `ssh -G <host>` prints rather than the alias, let later runs delegate rather than wait out the connect timeout first: Ask for it when the session will run more checks.
 - 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/delegate-host.js

@@ -8,7 +8,7 @@ import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
 import { isDelegationFlag } from "./invocation-args.js";
 import { reportVerdict } from "./presentation.js";
 import { chooseHost, probeHost } from "./remote-probe.js";
-import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG, DELEGATION_FAILURE_EXIT_CODE, deriveCheckoutPath, formatMisplacedDelegationWarning, NO_DELEGATE_FLAG, runRemotely, } from "./remote-run.js";
+import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG, DELEGATION_FAILURE_EXIT_CODE, deriveCheckoutPath, formatMisplacedDelegationWarning, readLastLine, runRemotely, } from "./remote-run.js";
 import { createSnapshot } from "./remote-snapshot.js";
 import { formatDisplayPath, loadUserConfig } from "./user-config.js";
 export async function resolveExecutionTarget(invocation) {
@@ -70,6 +70,7 @@ const PROBE_RESULT_PHRASES = {
     busy: 'is busy',
     free: 'is free',
     'no-answer': 'did not answer the lock probe',
+    unreachable: 'could not be reached',
 };
 function composeForwardedArgs(command, parsedArgs) {
     return [
@@ -103,6 +104,9 @@ function describeDelegationSource(target, parsedArgs, env) {
             return parsedArgs.delegateHosts === undefined ? DELEGATE_FLAG : DELEGATE_TO_FLAG;
     }
 }
+function describeUnreachableHost(host, sshMessage) {
+    return sshMessage === '' ? `${host} did not answer` : `${host} did not answer: ${sshMessage}`;
+}
 async function delegate(options) {
     const { invocation, remoteEnv, target } = options;
     const { command, context, cwd, env, parsedArgs, stderr, stdout } = invocation;
@@ -114,10 +118,17 @@ async function delegate(options) {
             reportError(`Cannot delegate to ${listedHosts}: ${snapshot.reason}`, stderr);
             return { kind: 'refused', exitCode: 1 };
         }
-        stderr.write(`nmr: running ${command} here rather than on ${listedHosts}: ${snapshot.reason}\n`);
+        stderr.write(formatRunHereLine(command, listedHosts, snapshot.reason));
+        return { kind: 'here' };
+    }
+    const choice = snapshot.ok
+        ? await resolveHost(target.hosts, snapshot.toplevel, env, stderr)
+        : { kind: 'chosen', host: target.hosts[0] };
+    if (choice.kind === 'unreachable' && target.source === 'config') {
+        stderr.write(formatRunHereLine(command, listedHosts, describeUnreachableHost(choice.host, choice.sshMessage)));
         return { kind: 'here' };
     }
-    const host = snapshot.ok ? await resolveHost(target.hosts, snapshot.toplevel, env, stderr) : target.hosts[0];
+    const { host } = choice;
     const retained = { stderr: createBoundedBuffer(), stdout: createBoundedBuffer() };
     const result = snapshot.ok
         ? await runRemotely({
@@ -142,14 +153,13 @@ async function delegate(options) {
         treeId: snapshot.ok ? snapshot.treeId : undefined,
     };
     if (!result.ok) {
+        if (target.source === 'config' && 'phase' in result && result.phase === 'prepare' && result.isUnreachable) {
+            stderr.write(formatRunHereLine(command, listedHosts, describeUnreachableHost(host, readLastLine(result.output))));
+            return { kind: 'here' };
+        }
         if (result.output.trim() !== '') {
             stderr.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
         }
-        if (target.source === 'config' && 'phase' in result && result.phase === 'prepare') {
-            const configPath = formatDisplayPath(target.configPath, env);
-            stderr.write(`nmr: ${configPath} sent ${command} to ${listedHosts}; ask for network access to ${listedHosts}, ` +
-                `or run it here with nmr ${NO_DELEGATE_FLAG} ${command}\n`);
-        }
         return {
             ...ran,
             exitCode: DELEGATION_FAILURE_EXIT_CODE,
@@ -162,10 +172,13 @@ async function delegate(options) {
         : { outcome: 'failed', durationMs, exitCode: result.exitCode };
     return { ...ran, exitCode: result.exitCode, outcome, passes: result.passes };
 }
+function formatRunHereLine(command, listedHosts, reason) {
+    return `nmr: running ${command} here rather than on ${listedHosts}: ${reason}\n`;
+}
 async function resolveHost(hosts, toplevel, env, stderr) {
     const [first, ...rest] = hosts;
     if (rest.length === 0) {
-        return first;
+        return { kind: 'chosen', host: first };
     }
     const checkoutPath = deriveCheckoutPath(os.hostname(), toplevel);
     return chooseHost({

package/dist/esm/help.js

@@ -53,6 +53,7 @@ export function generateHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
         'Files:',
         "  ~/.config/nmr/config.ts     User config: this machine's delegation hosts, and when to use them",
         '                              ($XDG_CONFIG_HOME/nmr/config.ts when that is set)',
+        '                              A command that it sends runs here when no host answers',
         '',
         'Workspace commands:',
     ];

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

@@ -1,6 +1,37 @@
 import { type HostList } from './remote-run.js';
-/** What a probe found on a host: whether a delegation started now would wait there, or that the host did not answer. */
-export type ProbeResult = 'busy' | 'free' | 'no-answer';
+/**
+ * The host on which to run, or that `ssh` could not connect to any host, with what it printed for the first one
+ * listed.
+ */
+export type HostChoice = {
+    kind: 'chosen';
+    host: string;
+} | {
+    kind: 'unreachable';
+    host: string;
+    sshMessage: string;
+};
+/**
+ * The host that the probe results settle on, or that every host is unreachable.
+ *
+ * @internal
+ */
+export type HostSelection = {
+    kind: 'chosen';
+    host: string;
+} | {
+    kind: 'unreachable';
+};
+/** What a probe found, with the last line that `ssh` printed when it could not connect. */
+export interface ProbeReport {
+    result: ProbeResult;
+    sshMessage: string;
+}
+/**
+ * What a probe found on a host: whether a delegation started now would wait there, that the host connected but did
+ * not answer, or that `ssh` could not connect to it.
+ */
+export type ProbeResult = 'busy' | 'free' | 'no-answer' | 'unreachable';
 /**
  * Probes every host at once and resolves to the one on which to run, per `selectHost`, as soon as the results that
  * have arrived settle it. Reports each result that arrives before then, and aborts the probes still running once it
@@ -9,23 +40,24 @@ export type ProbeResult = 'busy' | 'free' | 'no-answer';
 export declare function chooseHost(options: {
     hosts: HostList;
     onSettled: (host: string, result: ProbeResult) => void;
-    probe: (host: string, signal: AbortSignal) => Promise<ProbeResult>;
-}): Promise<string>;
+    probe: (host: string, signal: AbortSignal) => Promise<ProbeReport>;
+}): Promise<HostChoice>;
 /**
  * Asks `host` whether a delegation from this checkout would wait there: whether its machine lock, or the lock of the
- * checkout at `checkoutPath`, has a live holder. A host that fails to run the probe, or does not print its report,
- * did not answer.
+ * checkout at `checkoutPath`, has a live holder. A host to which `ssh` cannot connect is unreachable, and one that
+ * fails to run the probe, or does not print its report, did not answer.
  */
 export declare function probeHost(options: {
     checkoutPath: string;
     env: NodeJS.ProcessEnv;
     host: string;
     signal: AbortSignal;
-}): Promise<ProbeResult>;
+}): Promise<ProbeReport>;
 /**
  * Returns the host on which to run, or `undefined` while a host whose result could change the choice has not
- * answered: the first free host in list order, otherwise the first busy one, otherwise the first host.
+ * answered: the first free host in list order, otherwise the first busy one, otherwise the first one that connected.
+ * When `ssh` could not connect to any host, returns that every host is unreachable.
  *
  * @internal
  */
-export declare function selectHost(hosts: HostList, results: ReadonlyMap<string, ProbeResult>): string | undefined;
+export declare function selectHost(hosts: HostList, results: ReadonlyMap<string, ProbeResult>): HostSelection | undefined;

package/dist/esm/remote-probe.js

@@ -4,33 +4,38 @@ import { isObject } from "./helpers/type-guards.js";
 import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "./machine-lock.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { probeHostLocks } from "./remote-probe-host.js";
-import { runSsh } from "./remote-run.js";
+import { DELEGATION_FAILURE_EXIT_CODE, readLastLine, runSsh } from "./remote-run.js";
 export function chooseHost(options) {
     const { hosts, onSettled, probe } = options;
     const controller = new AbortController();
     const results = new Map();
+    const sshMessages = new Map();
     return new Promise((resolve) => {
         for (const host of hosts) {
             void settle(host, resolve);
         }
     });
     async function settle(host, resolve) {
-        let result;
+        let report;
         try {
-            result = await probe(host, controller.signal);
+            report = await probe(host, controller.signal);
         }
         catch {
-            result = 'no-answer';
+            report = { result: 'no-answer', sshMessage: '' };
         }
         if (controller.signal.aborted)
             return;
-        results.set(host, result);
-        onSettled(host, result);
-        const chosen = selectHost(hosts, results);
-        if (chosen === undefined)
+        results.set(host, report.result);
+        sshMessages.set(host, report.sshMessage);
+        onSettled(host, report.result);
+        const selection = selectHost(hosts, results);
+        if (selection === undefined)
             return;
         controller.abort();
-        resolve(chosen);
+        const [first] = hosts;
+        resolve(selection.kind === 'chosen'
+            ? selection
+            : { kind: 'unreachable', host: first, sshMessage: sshMessages.get(first) ?? '' });
     }
 }
 export async function probeHost(options) {
@@ -43,17 +48,20 @@ export async function probeHost(options) {
     };
     const source = `(${probeHostLocks.toString()})(JSON.parse(process.argv[1]));`;
     const { exitCode, output } = await runSsh(host, `exec node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`, env, signal);
+    if (exitCode === DELEGATION_FAILURE_EXIT_CODE) {
+        return { result: 'unreachable', sshMessage: readLastLine(output) };
+    }
     if (exitCode !== 0) {
-        return 'no-answer';
+        return { result: 'no-answer', sshMessage: '' };
     }
     const busy = output
         .split('\n')
         .map(readBusyField)
         .findLast((value) => value !== undefined);
     if (busy === undefined) {
-        return 'no-answer';
+        return { result: 'no-answer', sshMessage: '' };
     }
-    return busy ? 'busy' : 'free';
+    return { result: busy ? 'busy' : 'free', sshMessage: '' };
 }
 export function selectHost(hosts, results) {
     for (const host of hosts) {
@@ -62,10 +70,12 @@ export function selectHost(hosts, results) {
             return undefined;
         }
         if (result === 'free') {
-            return host;
+            return { kind: 'chosen', host };
         }
     }
-    return hosts.find((host) => results.get(host) === 'busy') ?? hosts[0];
+    const host = hosts.find((candidate) => results.get(candidate) === 'busy') ??
+        hosts.find((candidate) => results.get(candidate) === 'no-answer');
+    return host === undefined ? { kind: 'unreachable' } : { kind: 'chosen', host };
 }
 function readBusyField(line) {
     try {

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

@@ -10,6 +10,8 @@ export declare const DELEGATE_TO_FLAG = "--delegate-to";
 export declare const DELEGATION_FAILURE_EXIT_CODE = 255;
 /** The flag that runs the command here, whatever `NMR_DELEGATE` or the user config says. */
 export declare const NO_DELEGATE_FLAG = "--no-delegate";
+/** Names the ssh command that the environment supplies, which git and nmr run in place of plain `ssh`. */
+export declare const SSH_COMMAND_ENV_VAR = "GIT_SSH_COMMAND";
 /** 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[];
 /** Candidate hosts in order of preference. */
@@ -19,7 +21,7 @@ export type RemotePhase = 'check out' | 'install' | 'prepare' | 'push' | 'run';
 /**
  * The status of a delegated command and the pass-manifest entries that its run reported, unvalidated, or the phase
  * that kept it from finishing and what that phase printed, with how long the delegation waited for another
- * delegation's checkout.
+ * delegation's checkout. A failed `prepare` also reports whether `ssh` could not connect to the host.
  */
 export type RemoteRunResult = {
     ok: true;
@@ -28,11 +30,32 @@ export type RemoteRunResult = {
     waitedMs: number;
 } | {
     ok: false;
+    isUnreachable: boolean;
     message: string;
     output: string;
-    phase: RemotePhase;
+    phase: 'prepare';
+    waitedMs: number;
+} | {
+    ok: false;
+    message: string;
+    output: string;
+    phase: Exclude<RemotePhase, 'prepare'>;
     waitedMs: number;
 };
+/**
+ * Returns the `GIT_SSH_COMMAND` with which `git push` reaches the host: the environment's ssh command, or plain
+ * `ssh`, followed by nmr's own options.
+ *
+ * @internal
+ */
+export declare function composeGitSshCommand(env: NodeJS.ProcessEnv): string;
+/**
+ * Returns the argv that runs `remoteCommand` on `host` with nmr's own options. An ssh command in the environment
+ * runs under `/bin/sh` with the arguments appended, as git runs it, because it may contain shell quoting.
+ *
+ * @internal
+ */
+export declare function composeSshArgv(env: NodeJS.ProcessEnv, host: string, remoteCommand: string): string[];
 /**
  * Returns the checkout's path on the host, relative to its home directory: a key derived from this machine and the
  * repository, followed by the repository's own directory name, which nmr on the host reports as the root's scope.
@@ -45,6 +68,8 @@ export declare function deriveCheckoutPath(hostname: string, toplevel: string):
  * command rather than a flag to nmr.
  */
 export declare function formatMisplacedDelegationWarning(command: string, style: OutputStyle): string;
+/** Returns the last line of `output` that is not blank, trimmed, or an empty string when there is none. */
+export declare function readLastLine(output: string): string;
 /**
  * Runs an nmr invocation on `host` against a snapshot of the local working tree, streaming the command's output to
  * `stdout` and `stderr` and returning its exit status.

package/dist/esm/remote-run.js

@@ -15,7 +15,18 @@ export const DELEGATE_FLAG = '--delegate';
 export const DELEGATE_TO_FLAG = '--delegate-to';
 export const DELEGATION_FAILURE_EXIT_CODE = 255;
 export const NO_DELEGATE_FLAG = '--no-delegate';
+export const SSH_COMMAND_ENV_VAR = 'GIT_SSH_COMMAND';
 export const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10'];
+export function composeGitSshCommand(env) {
+    return [resolveSshCommand(env) ?? 'ssh', ...SSH_OPTIONS].join(' ');
+}
+export function composeSshArgv(env, host, remoteCommand) {
+    const sshCommand = resolveSshCommand(env);
+    const sshArgs = [...SSH_OPTIONS, host, remoteCommand];
+    return sshCommand === undefined
+        ? ['ssh', ...sshArgs]
+        : ['/bin/sh', '-c', `${sshCommand} "$@"`, sshCommand, ...sshArgs];
+}
 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));
@@ -25,13 +36,26 @@ export function formatMisplacedDelegationWarning(command, style) {
         `command name are passed to \`${command}\`, not read by nmr. Write them before it: ` +
         `\`nmr ${DELEGATE_TO_FLAG} <host> ${command}\`.`);
 }
+export function readLastLine(output) {
+    return (output
+        .split('\n')
+        .map((line) => line.trim())
+        .findLast((line) => line !== '') ?? '');
+}
 export async function runRemotely(options) {
     const { command, 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', waitedMs: 0 };
+        return {
+            ok: false,
+            isUnreachable: prepare.exitCode === DELEGATION_FAILURE_EXIT_CODE,
+            message: `could not prepare ${host}`,
+            output: prepare.output,
+            phase: 'prepare',
+            waitedMs: 0,
+        };
     }
     const push = await runProcess([
         'git',
@@ -42,7 +66,7 @@ export async function runRemotely(options) {
         `--receive-pack=${RECEIVE_PACK_COMMAND}`,
         `${host}:${checkoutPath}`,
         `${snapshot.sha}:${SNAPSHOT_REF}`,
-    ], { cwd: snapshot.toplevel, env: { ...env, GIT_SSH_COMMAND: ['ssh', ...SSH_OPTIONS].join(' ') } });
+    ], { cwd: snapshot.toplevel, env: { ...env, [SSH_COMMAND_ENV_VAR]: composeGitSshCommand(env) } });
     if (push.exitCode !== 0) {
         return { ok: false, message: `could not push to ${host}`, output: push.output, phase: 'push', waitedMs: 0 };
     }
@@ -92,7 +116,7 @@ export async function runRemotely(options) {
             statusFile,
         },
     });
-    const session = await runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], {
+    const session = await runProcess(composeSshArgv(env, host, wrapRemoteScript(script)), {
         env,
         isStreaming: true,
         stderr: demultiplexer.stream,
@@ -121,7 +145,7 @@ export async function runRemotely(options) {
     return { ok: true, exitCode: session.exitCode, passes, waitedMs };
 }
 export function runSsh(host, script, env, signal) {
-    return runProcess(['ssh', ...SSH_OPTIONS, host, wrapRemoteScript(script)], { env, signal });
+    return runProcess(composeSshArgv(env, host, wrapRemoteScript(script)), { env, signal });
 }
 export function wrapRemoteScript(script) {
     return `exec /bin/sh -c ${quoteForShell(`${LOGIN_PATH_PREAMBLE}\n${script}`)}`;
@@ -157,6 +181,10 @@ function forwardChunk(chunk, stream, buffer) {
     }
     stream.write(chunk);
 }
+function resolveSshCommand(env) {
+    const sshCommand = env[SSH_COMMAND_ENV_VAR];
+    return sshCommand === undefined || sshCommand === '' ? undefined : sshCommand;
+}
 function runProcess(argv, options) {
     const { cwd, env, isStreaming = false, signal, stderr, stdout } = options;
     const [file = '', ...args] = argv;

package/docs/delegate.md

@@ -48,7 +48,7 @@ The first rule that applies decides where a command runs:
 | 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                                                                                           |
+| 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; here with one line when no host answers                                                  |
 | 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.
@@ -57,7 +57,7 @@ The first rule that applies decides where a command runs:
 
 ### 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.
+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 busy host; and when no host reported either, on the first host that `ssh` connected to. When `ssh` connects to none of them, a delegation that the user config decided [runs here](#when-no-host-answers) without a further attempt, and a requested one fails at `prepare` on the first host. A requested delegation never runs the command here, because the machine that delegates is the one that delegation protects.
 
 ```console
 $ NMR_DELEGATE=imac2,imac3 nmr ci
@@ -128,14 +128,20 @@ 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:
+### When no host answers
+
+A host answers when `ssh` connects to it. When the user config's `when` sent the command and `ssh` cannot connect to any of its hosts, nmr runs the command here, as `--no-delegate` would, after one line that names the hosts and what `ssh` reported for the first one that it tried:
 
 ```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
+nmr: running ci here rather than on imac2, imac3: imac2 did not answer: ssh: connect to host imac2 port 22: Operation timed out
 ```
 
+The run here is an ordinary local run: It takes the [machine lock](machine-lock.md), reports a verdict that does not name a host, and records a pass earned here. The fallback waits out the connect timeout on every invocation, so a machine that is away from its hosts for long is quicker with `--no-delegate` or a `when` that does not match.
+
+Every other failure still exits 255: a delegation that `--delegate`, `--delegate-to`, or `NMR_DELEGATE` requested, which the developer asked to run elsewhere, and a failure on a host that answered, at `prepare` or later, which is a fault there to fix.
+
 ## 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.
+- **SSH that does not prompt.** nmr runs the ssh command that `GIT_SSH_COMMAND` names, evaluated by `/bin/sh` as git evaluates it, or plain `ssh` when the variable is unset or empty, and adds `BatchMode=yes` and a connect timeout after the command's own options, so an option that the command sets itself takes precedence. Under `BatchMode=yes`, 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. 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.
+- **A sandboxed agent session needs network access to the host.** A sandbox that allows only HTTP egress refuses `ssh`. Under `when: 'agent'`, every check that the session runs then [runs here](#when-no-host-answers) after the connect timeout, and a requested delegation fails at `prepare`, until the session has that access. The Claude Code sandbox reaches a host only through the proxy that its `GIT_SSH_COMMAND` names, and it admits the host by the name that ssh connects to, which is the `HostName` that `~/.ssh/config` gives the alias (`ssh -G <host>` prints it), on port 22: For `imac2` with `HostName skypilot-imac2.local`, the sandbox must admit `skypilot-imac2.local:22`, not `imac2`. Nobody has confirmed whether the proxy resolves an mDNS name such as `skypilot-imac2.local`: When a delegation to such a host does not answer, and `ssh` reports `sandbox proxy: <name>:22: 502 Bad Gateway`, give the alias a `HostName` that is an IP address or a unicast DNS name, and have the sandbox admit that name's port 22.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.49.0",
+  "version": "0.50.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.4",
+    "@williamthorsen/nmr-core": "0.13.5",
     "@williamthorsen/toolbelt.errors": "0.8.3",
     "@williamthorsen/toolbelt.filesystem": "0.9.3",
     "glob": "13.0.6",