@williamthorsen/nmr 0.44.0 → 0.45.0

package/.readyup/manifest.json

@@ -5,6 +5,7 @@
       "bundledDependencies": {
         "@williamthorsen/toolbelt.errors": "0.8.3",
         "@williamthorsen/toolbelt.filesystem": "0.9.3",
+        "@williamthorsen/toolbelt.packaging": "0.6.3",
         "@williamthorsen/toolbelt.terminal": "0.2.1",
         "ansi-regex": "6.4.0",
         "ansi-styles": "6.2.3",
@@ -29,11 +30,6 @@
           "kind": "module",
           "path": "../../nmr-core/dist/esm/cache-store.js"
         },
-        {
-          "hash": "a5f44396",
-          "kind": "module",
-          "path": "../../nmr-core/dist/esm/findPackageRoot.js"
-        },
         {
           "hash": "54384dca",
           "kind": "module",
@@ -55,7 +51,7 @@
           "path": "../../nmr-core/dist/esm/helpers/workspace-patterns.js"
         },
         {
-          "hash": "1467293d",
+          "hash": "191f7c24",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/index.js"
         },
@@ -64,11 +60,6 @@
           "kind": "module",
           "path": "../../nmr-core/dist/esm/parseArgs.js"
         },
-        {
-          "hash": "a7efc38f",
-          "kind": "module",
-          "path": "../../nmr-core/dist/esm/readPackageVersion.js"
-        },
         {
           "hash": "14547f78",
           "kind": "module",
@@ -95,7 +86,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "747d941f",
+          "hash": "22efcac6",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -103,7 +94,7 @@
           ]
         },
         {
-          "hash": "b23f5a52",
+          "hash": "7e066d18",
           "kind": "module",
           "path": "../src/config.ts"
         },
@@ -122,6 +113,11 @@
           "kind": "module",
           "path": "../src/helpers/config-path.ts"
         },
+        {
+          "hash": "a663548a",
+          "kind": "module",
+          "path": "../src/helpers/escapeControlCharacters.ts"
+        },
         {
           "hash": "47249ca4",
           "kind": "module",
@@ -153,17 +149,17 @@
           "path": "../src/resolve-scripts.ts"
         },
         {
-          "hash": "6ae507a5",
+          "hash": "15247f0e",
           "kind": "module",
           "path": "../src/resolver.ts"
         },
         {
-          "hash": "c4b31275",
+          "hash": "ed585ab6",
           "kind": "module",
           "path": "../src/steps.ts"
         },
         {
-          "hash": "19dec003",
+          "hash": "d1e8e302",
           "kind": "module",
           "path": "../src/tiers.ts"
         },
@@ -193,7 +189,7 @@
       "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
       "sourceHash": "aaeb1a84",
-      "targetHash": "25b7edfb"
+      "targetHash": "a8b07f51"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.45.0 — 2026-10-12
+
+### 🎉 Features
+
+- Adds `maintenance.auto=false` to the git config that the Vitest git-isolation setup file injects, so that a git command run by a test does not start a detached `git maintenance` process that can still be writing under `.git` when the test removes the repository. (#1033)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr-fmt` failed a run in which every path matched by the pathspecs was one that it skips, such as a symlink, a submodule gitlink, or an unreadable file, and makes such a run exit 0 and name the skipped paths on stderr. (#1010)
+- Fixes the issue that a `rootScripts` or `workspaceScripts` entry in `.config/nmr.config.ts` that names its own key, as a shell segment or as a step-list element, re-entered nmr without bound, by rejecting the entry when the config loads with an error that names the file, the field, the key, and the edit that resolves it. (#1011)
+- Fixes the issue that a package's own `package.json` entry running `nmr -R <same command>` re-entered that package without bound instead of being discarded or rejected as a self-reference. (#1011)
+- Fixes the issue that nmr treated a root entry such as `pnpm --recursive exec nmr build` as a re-invocation of its own command, because it ignored the `-r`, `--filter`, and `-w` flags that pnpm applies to the nmr that it launches. (#1011)
+- Fixes the issue that `nmr` hung when a script entry re-entered its own command in the same directory without nmr recognizing the self-reference, as `nmr -F own-pkg build` in `own-pkg`'s own `build` or a cycle through two entries does, by failing the run with an error that names the command and the directory and lists the commands that the run had entered, outermost first. (#1012)
+- 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)
+
+### ♻️ 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)
+
+### 🧪 Tests
+
+- Replaces the `GIT_CEILING_DIRECTORIES` stub with a `GIT_DIR` stub that points to a missing path in the no-repository test of `check-cache-gate.tool.test.ts`, and sets `maintenance.auto` to `false` in the file's fixture repository, so that git neither finds a leftover of the removed `repo/.git` nor starts a detached maintenance process that writes under `.git`. (#1032)
+
 ## 0.44.0 — 2026-10-11
 
 ### 🎉 Features

package/README.md

@@ -5,28 +5,21 @@
 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.44.0 (2026-10-11)
+## Release notes — v0.45.0 (2026-10-12)
 
 ### 🎉 Features
 
-- Enables Prettier's content-keyed cache in `nmr-fmt` (run by `nmr fmt` and `nmr fmt:check`), which skips each file whose content, Prettier version, resolved options, and lockfile are unchanged since a run that passed it, and adds `--no-cache` and `NMR_NO_CACHE=1` to bypass it. (#993)
-- Adds the `shouldRunInBackground` field to a composite element in `.config/nmr.config.ts`, which starts the step, runs the steps after it without waiting, prints the step's output whole after the step ends, and fails the composite if the step fails. (#1003)
-- Adds a `self-hosted runner` checklist to nmr's readyup kit, which reads the repo's GitHub settings through `gh`, recommends setting `CI_RUNS_ON` when a private repo with an online self-hosted runner and compatible workflows has not set it, and warns about each failing condition once the variable is set. (#1006)
-- Adds the root-only config key `selfHostedRunner.exempt`, a non-empty reason that stops the kit from recommending `CI_RUNS_ON` for a repo that qualifies for the self-hosted runners but stays off them. (#1006)
-
-### 🪦 Removed
-
-- 🚨 **Breaking:** Removes the zero-argument form of `getDefaultRootScripts` from the `@williamthorsen/nmr/scripts` export, which now requires the monorepo root so that it can read the declared workspaces. (#992)
+- Adds `maintenance.auto=false` to the git config that the Vitest git-isolation setup file injects, so that a git command run by a test does not start a detached `git maintenance` process that can still be writing under `.git` when the test removes the repository. (#1033)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `root:lint`, `root:lint:check`, and `root:lint:strict` linted every workspace outside `packages/` under the root ESLint config, by excluding each workspace package that `pnpm-workspace.yaml` declares, with its `!` exclusions honored, in place of the fixed `packages/**`. (#992)
-- Fixes the issue that `defineConfig({ mode: undefined })` emptied the `nmr upgrade` report, by translating a cleared `mode` into the `'default'` mode of taze (the upgrade tool that `nmr upgrade` runs), which follows the range that each dependency declares. (#1008)
-
-### ⚡ Performance
-
-- Sets `maxWorkers: 3` on every project built by `defineVitestConfig` and `defineRootVitestConfig` when the machine has 2 or fewer cores, such as GitHub's standard runner for a private repo, on which Vitest's default ran every test file serially on one worker. (#994)
-- Changes the default `check` and `check:strict` to start lint first and run it in the background, so that a local check, `nmr ci`, and `nmr prepush` no longer wait for type-aware lint to finish before typecheck, the format check, and the tests run. (#1003)
+- Fixes the issue that `nmr-fmt` failed a run in which every path matched by the pathspecs was one that it skips, such as a symlink, a submodule gitlink, or an unreadable file, and makes such a run exit 0 and name the skipped paths on stderr. (#1010)
+- Fixes the issue that a `rootScripts` or `workspaceScripts` entry in `.config/nmr.config.ts` that names its own key, as a shell segment or as a step-list element, re-entered nmr without bound, by rejecting the entry when the config loads with an error that names the file, the field, the key, and the edit that resolves it. (#1011)
+- Fixes the issue that a package's own `package.json` entry running `nmr -R <same command>` re-entered that package without bound instead of being discarded or rejected as a self-reference. (#1011)
+- Fixes the issue that nmr treated a root entry such as `pnpm --recursive exec nmr build` as a re-invocation of its own command, because it ignored the `-r`, `--filter`, and `-w` flags that pnpm applies to the nmr that it launches. (#1011)
+- Fixes the issue that `nmr` hung when a script entry re-entered its own command in the same directory without nmr recognizing the self-reference, as `nmr -F own-pkg build` in `own-pkg`'s own `build` or a cycle through two entries does, by failing the run with an error that names the command and the directory and lists the commands that the run had entered, outermost first. (#1012)
+- 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)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -124,7 +117,7 @@ Scripts resolve through three tiers. Higher tiers override lower ones:
 2. **Repo-wide config**: Additions and overrides in `.config/nmr.config.ts`
 3. **Per-package overrides**: Scripts in a package's `package.json`
 
-[Scripts and configuration](docs/scripts.md#three-tier-override-system) shows a worked example, how to skip a script for one package, and what nmr does with a `package.json` entry that re-invokes its own command.
+[Scripts and configuration](docs/scripts.md#three-tier-override-system) shows a worked example, how to skip a script for one package, and what nmr does with a `package.json` or `.config/nmr.config.ts` entry that re-invokes its own command.
 
 ## Pre and post hooks
 

package/agents/guidance/rulebooks/nmr.md

@@ -13,5 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `SKIP <scope>: <command>: passed …` and, when the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it. Read the replayed excerpt rather than running the check again: Never pass `--no-cache` to get a "real" run, which takes the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling when there are too many to fit. A skip without an excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
 - `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it. Output that you need in full is a recording to read rather than a command to run again. It runs nothing, and it is held to the tree rather than to the terminal: A recording made by a piped run prints for a reader at one. A composite prints its constituents' excerpts, not their transcripts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. When there is nothing to show, `--log` says so on one line, names which case it is, and exits non-zero.
 - 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 program supplied by the environment), `localhost` (a service 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.
+- 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 that the environment supplies), `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.
 - 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; 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/commands/fmt.d.ts

@@ -1,5 +1,7 @@
 export type FormatMode = 'check' | 'write';
 export interface FormatTargets {
+    /** Listed paths that Prettier cannot be handed, such as symlinks and submodule gitlinks. */
+    excludedFiles: string[];
     /** Paths relative to the working directory, as `git ls-files` emits them. */
     files: string[];
     /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
@@ -42,8 +44,8 @@ export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
  * `pathspecs` narrow the selection and are passed to git verbatim: They have git pathspec semantics rather
  * than shell glob semantics.
  *
- * A listed path that this process is denied access to is set aside in `unreadableFiles`; any other stat failure
- * fails the resolution.
+ * A listed path that Prettier cannot be handed is set aside in `excludedFiles`, and one that this process is denied
+ * access to in `unreadableFiles`; any other stat failure fails the resolution.
  */
 export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]): ResolveTargetsResult;
 /** @internal */

package/dist/esm/commands/fmt.js

@@ -33,15 +33,20 @@ export async function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${resolvedTargets.error}`);
         return 1;
     }
-    const { files, ignorePaths, repositoryRoot, unreadableFiles } = resolvedTargets.targets;
+    const { excludedFiles, files, ignorePaths, repositoryRoot, unreadableFiles } = resolvedTargets.targets;
     for (const { file, code } of unreadableFiles) {
         process.stderr.write(`nmr-fmt: skipped ${file}, which cannot be read (${code})\n`);
     }
     if (files.length === 0) {
-        if (parsedArgs.pathspecs.length > 0) {
-            reportError(`nmr-fmt: the pathspecs did not match any formattable file: ${parsedArgs.pathspecs.join(', ')}`);
+        if (parsedArgs.pathspecs.length === 0)
+            return 0;
+        if (excludedFiles.length === 0 && unreadableFiles.length === 0) {
+            reportError(`nmr-fmt: the pathspecs did not match any file that git lists: ${parsedArgs.pathspecs.join(', ')}`);
             return 1;
         }
+        if (excludedFiles.length > 0) {
+            process.stderr.write(`nmr-fmt: nothing to format; skipped paths that are not regular files: ${excludedFiles.join(', ')}\n`);
+        }
         return 0;
     }
     const cli = resolvePrettierCli(cwd);
@@ -84,6 +89,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
     const ignoreFiles = runGit([...LIST_FILES_ARGS, '--', IGNORE_FILE_PATHSPEC], repositoryRoot);
     if (!ignoreFiles.ok)
         return ignoreFiles;
+    const excludedFiles = [];
     const files = [];
     const unreadableFiles = [];
     const listedPaths = dedupe(splitNulSeparated(listedFiles.stdout));
@@ -91,6 +97,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
         const status = classifyListedFile(cwd, file);
         switch (status.kind) {
             case 'excluded':
+                excludedFiles.push(file);
                 break;
             case 'failed':
                 return { ok: false, error: status.error };
@@ -108,6 +115,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
     return {
         ok: true,
         targets: {
+            excludedFiles: excludedFiles.toSorted(),
             files: files.toSorted(),
             ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
             repositoryRoot,

package/dist/esm/config.js

@@ -9,11 +9,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { resolveConfigPath } from "./helpers/config-path.js";
+import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
-import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { findUnexpressibleToken } from "./steps.js";
+import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { buildRootRegistry, buildWorkspaceRegistry, describeScript, readPackageJsonScripts } from "./resolver.js";
+import { findUnexpressibleToken, readSelfReference, readStepListSelfReference, } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
@@ -35,6 +37,10 @@ const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommand
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_SELF_HOSTED_RUNNER_KEYS = ['exempt'];
 const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments', 'shouldRunInBackground'];
+const SCRIPT_FIELDS = [
+    { field: 'rootScripts', scope: 'root' },
+    { field: 'workspaceScripts', scope: 'workspaceRegistry' },
+];
 const RETIRED_STEP_KEYS = new Map([['declinesArgs', 'shouldDeclineArguments']]);
 function isScriptRecord(value) {
     if (!isObject(value))
@@ -286,7 +292,9 @@ export async function loadConfig(baseDir) {
 }
 export async function loadRootConfig(monorepoRoot) {
     const config = await loadConfig(monorepoRoot);
-    assertTierKeys(config, CONFIG_TIERS.root, resolveConfigPath(monorepoRoot));
+    const configPath = resolveConfigPath(monorepoRoot);
+    assertTierKeys(config, CONFIG_TIERS.root, configPath);
+    assertNoSelfReferences(config, configPath, monorepoRoot);
     return config;
 }
 export async function loadWorkspaceConfig(packageDir) {
@@ -302,6 +310,30 @@ function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`${prefix}${key}\` was renamed to \`${prefix}${replacement}\`.`);
     }
 }
+function assertNoSelfReferences(config, configPath, monorepoRoot) {
+    for (const { field, scope } of SCRIPT_FIELDS) {
+        const scripts = config[field] ?? {};
+        for (const [key, script] of Object.entries(scripts)) {
+            const selfReference = typeof script === 'string'
+                ? readSelfReference({ commandName: key, scope, script })
+                : readStepListSelfReference({
+                    commandName: key,
+                    elements: script.map((element) => (typeof element === 'string' ? element : element.run)),
+                    scope,
+                });
+            if (selfReference === undefined)
+                continue;
+            const defaults = field === 'rootScripts' ? getDefaultRootScripts(monorepoRoot) : getDefaultWorkspaceScripts();
+            const remedy = formatSelfReferenceRemedy({
+                isDefault: !isHookName(key) && Object.hasOwn(defaults, key),
+                key,
+                selfReference,
+            });
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${field}.${key}\` re-invokes \`${key}\` ` +
+                `(\`${escapeControlCharacters(describeScript(script))}\`), which would re-enter nmr without bound. ${remedy}`);
+        }
+    }
+}
 function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
     const unrecognizedKeys = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
     if (unrecognizedKeys.length === 0) {
@@ -324,3 +356,14 @@ function formatKeyList(keys, prefix) {
         .map((key) => `\`${prefix}${key}\``)
         .join(', ');
 }
+function formatSelfReferenceRemedy(options) {
+    const { isDefault, key, selfReference } = options;
+    if (isDefault) {
+        return selfReference === 'sole'
+            ? `Delete the entry: nmr's own \`${key}\` then runs.`
+            : `Delete the entry and move the steps that it adds to a \`${key}:pre\` or \`${key}:post\` script.`;
+    }
+    return selfReference === 'sole'
+        ? 'Delete the entry.'
+        : `Delete the re-invocation: \`${key}\` runs the steps beside it.`;
+}

package/dist/esm/entry-chain.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Carries the entries that a run is inside, from the outermost inward, down to every process that it spawns. An
+ * entry that finds itself already on the chain would re-enter itself without bound.
+ */
+export declare const ENTRY_CHAIN_ENV_VAR = "NMR_ENTRY_CHAIN";
+/** A command that an invocation resolved, and the directory whose registry it resolved the command from. */
+export interface ChainEntry {
+    command: string;
+    dir: string;
+}
+/**
+ * Admits an invocation onto the chain that it inherited, returning the environment that its steps inherit in turn.
+ * Throws a `UserError` when an ancestor in the run is already running the same command from the same directory, or
+ * when the inherited chain cannot be read.
+ *
+ * Records the directory's real path, so that a symlinked checkout or a `/private` prefix seen by one process and not
+ * another cannot hide a repeat.
+ */
+export declare function enterChain(options: {
+    anchorDir: string;
+    command: string;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+}): NodeJS.ProcessEnv;

package/dist/esm/entry-chain.js

@@ -0,0 +1,57 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { isObject } from "./helpers/type-guards.js";
+import { UserError } from "./UserError.js";
+export const ENTRY_CHAIN_ENV_VAR = 'NMR_ENTRY_CHAIN';
+export function enterChain(options) {
+    const { anchorDir, command, env, monorepoRoot } = options;
+    const chain = readEntryChain(env[ENTRY_CHAIN_ENV_VAR]);
+    if (chain === undefined) {
+        throw new UserError(`${ENTRY_CHAIN_ENV_VAR} is not a chain that nmr wrote; unset it. nmr passes it to the processes that it starts.`);
+    }
+    const entry = { command, dir: realpathSync(anchorDir) };
+    const extendedChain = [...chain, entry];
+    if (chain.some((ancestor) => ancestor.command === entry.command && ancestor.dir === entry.dir)) {
+        throw new UserError(formatReentryError(extendedChain, realpathSync(monorepoRoot)));
+    }
+    return { ...env, [ENTRY_CHAIN_ENV_VAR]: JSON.stringify(extendedChain) };
+}
+function describeDir(dir, monorepoRoot) {
+    const relativeDir = path.relative(monorepoRoot, dir);
+    if (relativeDir === '') {
+        return 'root';
+    }
+    return relativeDir.startsWith('..') || path.isAbsolute(relativeDir) ? dir : relativeDir;
+}
+function formatReentryError(chain, monorepoRoot) {
+    const repeat = chain.at(-1);
+    if (repeat === undefined) {
+        throw new Error('A re-entry error needs the entry that repeats.');
+    }
+    const repeatDir = describeDir(repeat.dir, monorepoRoot);
+    const lines = chain.map((entry) => {
+        const isRepeat = entry.command === repeat.command && entry.dir === repeat.dir;
+        return `  ${entry.command} in ${describeDir(entry.dir, monorepoRoot)}${isRepeat ? '  (repeat)' : ''}`;
+    });
+    return [
+        `nmr re-entered \`${repeat.command}\` in ${repeatDir}, which this run is already running there, ` +
+            'so the run would never end. The entries that this run has entered, outermost first:',
+        ...lines,
+    ].join('\n');
+}
+function isChainEntry(value) {
+    return isObject(value) && typeof value['command'] === 'string' && typeof value['dir'] === 'string';
+}
+function readEntryChain(value) {
+    if (value === undefined || value === '') {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    return Array.isArray(parsed) && parsed.every(isChainEntry) ? parsed : undefined;
+}

package/dist/esm/glyphs.d.ts

@@ -5,5 +5,5 @@
  * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
-export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "package" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "package" | "clean" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

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

@@ -0,0 +1,10 @@
+/**
+ * Renders a declaration's text as the file stores it, so that a value written across lines is quoted on one line.
+ *
+ * A diagnostic names a declaration that the reader has to edit, and a JSON string contains an escape sequence where
+ * a shell would read a control character. The rendered escape keeps the diagnostic on one line, and it is the text
+ * for which the reader will search the file.
+ *
+ * Apply it only where the text is quoted: A comparison against the declaration reads the unescaped text.
+ */
+export declare function escapeControlCharacters(text: string): string;

package/dist/esm/helpers/escapeControlCharacters.js

@@ -0,0 +1,12 @@
+const NAMED_ESCAPES = new Map([
+    ['\n', String.raw `\n`],
+    ['\r', String.raw `\r`],
+    ['\t', String.raw `\t`],
+]);
+export function escapeControlCharacters(text) {
+    let escapedText = text;
+    for (const [char, escape] of NAMED_ESCAPES) {
+        escapedText = escapedText.split(char).join(escape);
+    }
+    return escapedText;
+}

package/dist/esm/resolver.js

@@ -108,12 +108,12 @@ export function findChainedSelfReference(packageDir, commandName) {
     if (script === undefined) {
         return undefined;
     }
-    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) === 'chained'
+    return readSelfReference({ commandName, scope: readPackageScope(packageDir), script }) === 'chained'
         ? script
         : undefined;
 }
 export function isSelfReferential(script, commandName, packageDir) {
-    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) !== undefined;
+    return readSelfReference({ commandName, scope: readPackageScope(packageDir), script }) !== undefined;
 }
 export function resolveScript(commandName, registry, packageDir, isWorkspaceRoot) {
     if (packageDir) {
@@ -137,3 +137,6 @@ export function resolveScript(commandName, registry, packageDir, isWorkspaceRoot
     }
     return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, isWorkspaceRoot) };
 }
+function readPackageScope(packageDir) {
+    return isMonorepoRoot(packageDir) ? 'root' : 'package';
+}