@williamthorsen/nmr 0.52.0 → 0.53.1

package/.meta/changelog.json

@@ -1,4 +1,80 @@
 [
+  {
+    "version": "0.53.1",
+    "date": "2026-10-28",
+    "sections": [
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Lead release-kit's function names with a transitive verb (#1137)",
+            "body": "Renames the functions in `release-kit`'s source and tests so that each name starts with a transitive verb that states its action, such as `releasePrepareTargets` to `prepareReleaseTargets`, `releaseWorkflow` to `renderReleaseWorkflow`, and `topologicalSort` to `sortTopologically`. The exports of `.` and `./config` stay the same.",
+            "hash": "a84d9ce0652754a417b85c3f9cd14a6e400c7b51"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "0.53.0",
+    "date": "2026-10-27",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds the time saved to the line that `nmr-compile` prints when it skips an unchanged package, as in `Skipping build, saved ~2.1s.`, when the skipped emit took at least a second. (#1112)",
+            "hash": "ead0549c50d886ef371cb03d979883e027b051c2",
+            "entry": 1
+          },
+          {
+            "description": "Adds `build skipped as unchanged` to the verdict line of a compile that hits the build cache, followed by the saved time when the recorded emit took at least a second, which nmr prints in a quiet run as well. (#1113)",
+            "hash": "02cbf9688061958d23230901120fc374e56ddfe7",
+            "entry": 1
+          },
+          {
+            "description": "Adds a `stated` field to the `--json` record of a passing command that stated its own outcome, such as `{\"kind\":\"build-unchanged\",\"savedMs\":2100}`, which records the saving whatever its size. (#1113)",
+            "hash": "02cbf9688061958d23230901120fc374e56ddfe7",
+            "entry": 2
+          },
+          {
+            "description": "Removes the 7-day `maturityPeriod` from the shared policy that `defineConfig` in `@williamthorsen/nmr/taze` supplies, so that `nmr upgrade` waits for the `minimumReleaseAge` set in `pnpm-workspace.yaml` (or pnpm's default) and no longer withholds releases that pnpm already resolves for other packages. (#1129)",
+            "hash": "e471e998babeb45ef0ca4db64a02fd0fd490702d",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that nmr reported a short or negative duration for a command's run, a delegated run, or a remote lock wait when the system clock was adjusted during that span. (#1112)",
+            "hash": "ead0549c50d886ef371cb03d979883e027b051c2",
+            "entry": 2
+          },
+          {
+            "description": "Fixes the issue that `nmr-fmt` never formatted a file whose name starts with `-` and rejected `--` as an unknown option, by making `nmr-fmt` accept `--` before its pathspecs and pass `--` to Prettier before the file list. (#1130)",
+            "hash": "d7cd93b2309c0668b7bcb82bf52bad5fc0a5b742",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Apply the naming conventions to nmr-core's identifiers (#1125)",
+            "body": "Renames the identifiers in nmr-core to follow the naming conventions, including the exported option keys of `updateManagedFile` and `writeFileWithCheck`, which change from `dryRun` and `overwrite` to `isDryRun` and `shouldOverwrite`, and the constant `GIT_OUTPUT_LIMIT`, which becomes `GIT_OUTPUT_LIMIT_BYTES`. Updates the call sites in nmr, release-kit, and v11y-check to the new names.",
+            "hash": "2cb60f628512ed6ec2273a219a7b6c71aa35b1bf"
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "0.52.0",
     "date": "2026-10-24",

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.43.0";
+export const __readyupVersion = "0.44.0";
 import { createRequire as __rdyCreateRequire } from 'node:module';
 const require = __rdyCreateRequire(import.meta.url);
 
@@ -7382,12 +7382,12 @@ import { isRecord, listTrackedFiles } from "readyup/check-utils";
 import { globSync } from "node:fs";
 import { basename, join, sep } from "node:path";
 
-// ../../node_modules/.pnpm/@williamthorsen+toolbelt.errors@0.8.4/node_modules/@williamthorsen/toolbelt.errors/dist/esm/4-release/isError.js
+// ../../node_modules/.pnpm/@williamthorsen+toolbelt.errors@0.9.0/node_modules/@williamthorsen/toolbelt.errors/dist/esm/4-release/isError.js
 function isError(error) {
   return error instanceof Error || Object.prototype.toString.call(error) === "[object Error]";
 }
 
-// ../../node_modules/.pnpm/@williamthorsen+toolbelt.errors@0.8.4/node_modules/@williamthorsen/toolbelt.errors/dist/esm/4-release/describeError.js
+// ../../node_modules/.pnpm/@williamthorsen+toolbelt.errors@0.9.0/node_modules/@williamthorsen/toolbelt.errors/dist/esm/4-release/describeError.js
 function describeError(error) {
   try {
     if (isError(error) && typeof error.message === "string" && error.message !== "") {
@@ -7732,12 +7732,12 @@ var import_yaml = __toESM(require_dist(), 1);
 // ../nmr-core/dist/esm/helpers/workspace-patterns.js
 import { globSync as globSync2 } from "node:fs";
 import path from "node:path";
-var MANIFEST = "package.json";
-var ALWAYS_EXCLUDED = ["**/node_modules/**"];
+var MANIFEST_FILENAME = "package.json";
+var ALWAYS_EXCLUDED_PATTERNS = ["**/node_modules/**"];
 function matchPackageDirs(monorepoRoot, includedPatterns, excludedPatterns) {
   const options = {
     cwd: monorepoRoot,
-    exclude: [...excludedPatterns, ...ALWAYS_EXCLUDED],
+    exclude: [...excludedPatterns, ...ALWAYS_EXCLUDED_PATTERNS],
     followSymlinks: true
   };
   const matches = globSync2([...includedPatterns], options);
@@ -7758,34 +7758,34 @@ function splitWorkspacePatterns(patterns) {
     if (pattern.trim() === "")
       continue;
     const isNegated = pattern.startsWith("!");
-    const target = isNegated ? excludedPatterns : includedPatterns;
-    target.push(buildManifestPattern(isNegated ? pattern.slice(1) : pattern));
+    const targetPatterns = isNegated ? excludedPatterns : includedPatterns;
+    targetPatterns.push(buildManifestPattern(isNegated ? pattern.slice(1) : pattern));
   }
   return { excludedPatterns, includedPatterns };
 }
 function buildManifestPattern(pattern) {
-  return `${pattern.replace(/\/?$/, "")}/${MANIFEST}`;
+  return `${pattern.replace(/\/?$/, "")}/${MANIFEST_FILENAME}`;
 }
 
 // ../nmr-core/dist/esm/workspace.js
-var WORKSPACE_MANIFEST = "pnpm-workspace.yaml";
+var WORKSPACE_MANIFEST_FILENAME = "pnpm-workspace.yaml";
 function isMonorepoRoot(dir) {
-  return existsSync(path2.join(dir, WORKSPACE_MANIFEST));
+  return existsSync(path2.join(dir, WORKSPACE_MANIFEST_FILENAME));
 }
 function resolveWorkspace(monorepoRoot) {
-  const manifestRead = readWorkspaceManifest(monorepoRoot);
-  if (manifestRead.kind === "absent") {
+  const manifestReadResult = readWorkspaceManifest(monorepoRoot);
+  if (manifestReadResult.kind === "absent") {
     return { kind: "not-a-workspace" };
   }
-  if (manifestRead.kind === "unreadable") {
+  if (manifestReadResult.kind === "unreadable") {
     return { cause: "unreadable-manifest", kind: "empty", patterns: [] };
   }
-  const packagesRead = readDeclaredPackages(manifestRead.value);
-  if (packagesRead.kind !== "patterns") {
-    const cause = packagesRead.kind === "absent" ? "no-packages-list" : "unreadable-packages";
+  const packagesReadResult = readDeclaredPackages(manifestReadResult.value);
+  if (packagesReadResult.kind !== "patterns") {
+    const cause = packagesReadResult.kind === "absent" ? "no-packages-list" : "unreadable-packages";
     return { cause, kind: "empty", patterns: [] };
   }
-  const { patterns } = packagesRead;
+  const { patterns } = packagesReadResult;
   const packageDirs = resolvePackageDirs(monorepoRoot, patterns);
   if (packageDirs.length > 0) {
     return { kind: "packages", packageDirs, patterns };
@@ -7818,12 +7818,12 @@ function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readWorkspaceManifest(monorepoRoot) {
-  const workspaceFile = path2.join(monorepoRoot, WORKSPACE_MANIFEST);
-  if (!existsSync(workspaceFile)) {
+  const workspaceManifestPath = path2.join(monorepoRoot, WORKSPACE_MANIFEST_FILENAME);
+  if (!existsSync(workspaceManifestPath)) {
     return { kind: "absent" };
   }
   try {
-    return { kind: "parsed", value: (0, import_yaml.parse)(readFileSync(workspaceFile, "utf8")) };
+    return { kind: "parsed", value: (0, import_yaml.parse)(readFileSync(workspaceManifestPath, "utf8")) };
   } catch {
     return { kind: "unreadable" };
   }
@@ -7838,11 +7838,11 @@ var UserError = class extends Error {
 };
 
 // src/workspace.ts
-var WORKSPACE_MANIFEST2 = "pnpm-workspace.yaml";
+var WORKSPACE_MANIFEST = "pnpm-workspace.yaml";
 function getWorkspacePackageDirs(monorepoRoot) {
   const resolution = resolveWorkspace(monorepoRoot);
   if (resolution.kind === "not-a-workspace") {
-    throw new UserError(`Not a monorepo root: no ${WORKSPACE_MANIFEST2} in ${monorepoRoot}`);
+    throw new UserError(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
   }
   return resolution.kind === "packages" ? resolution.packageDirs : [];
 }
@@ -9190,7 +9190,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "0.52.0" };
+  const pickedFields = { "version": "0.53.1" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -3,10 +3,13 @@
   "kits": [
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.errors": "0.8.4",
-        "@williamthorsen/toolbelt.filesystem": "0.9.4",
-        "@williamthorsen/toolbelt.packaging": "0.6.4",
-        "@williamthorsen/toolbelt.terminal": "0.2.1",
+        "@williamthorsen/toolbelt.datetime": "4.1.0",
+        "@williamthorsen/toolbelt.errors": "0.9.0",
+        "@williamthorsen/toolbelt.filesystem": "0.10.0",
+        "@williamthorsen/toolbelt.numbers": "7.3.0",
+        "@williamthorsen/toolbelt.objects": "4.4.0",
+        "@williamthorsen/toolbelt.packaging": "0.7.0",
+        "@williamthorsen/toolbelt.terminal": "0.3.0",
         "ansi-regex": "6.4.0",
         "ansi-styles": "6.2.3",
         "cli-truncate": "6.1.1",
@@ -24,7 +27,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 0.52.0",
+            "@williamthorsen/nmr >= 0.53.1",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -71,22 +74,22 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "aed52073",
+          "hash": "bf29a9a3",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/cache-store.js"
         },
         {
-          "hash": "81f1406b",
+          "hash": "bc0baa4a",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/collectChangedPaths.js"
         },
         {
-          "hash": "200f69f1",
+          "hash": "70d519e7",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/gitObjects.js"
         },
         {
-          "hash": "54384dca",
+          "hash": "14216f5f",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/gitOutputLimit.js"
         },
@@ -96,47 +99,52 @@
           "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
         },
         {
-          "hash": "1eb2b90c",
+          "hash": "0d7b3f7c",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
         },
         {
-          "hash": "41232d10",
+          "hash": "c1eae24e",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/helpers/workspace-patterns.js"
         },
         {
-          "hash": "191f7c24",
+          "hash": "dcd24627",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/index.js"
         },
         {
-          "hash": "89d3e3b4",
+          "hash": "a2053951",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/parseArgs.js"
         },
         {
-          "hash": "7915ba49",
+          "hash": "9104fb90",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/runGit.js"
         },
         {
-          "hash": "14547f78",
+          "hash": "46b44e18",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/terminal.js"
         },
         {
-          "hash": "3c395f31",
+          "hash": "85afaf3e",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/timer.js"
+        },
+        {
+          "hash": "5ae3e980",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/updateManagedFile.js"
         },
         {
-          "hash": "2224ec3a",
+          "hash": "00d00fae",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/workspace.js"
         },
         {
-          "hash": "24bde686",
+          "hash": "d377c37c",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
         },
@@ -186,7 +194,7 @@
           "path": "lib/setup.ts"
         },
         {
-          "hash": "400757e6",
+          "hash": "64995a53",
           "kind": "module",
           "path": "lib/shared-configs.ts"
         },
@@ -201,7 +209,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "0d9124f7",
+          "hash": "b54c684e",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -316,10 +324,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.43.0",
+      "readyupVersion": "0.44.0",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "547201fd"
+      "targetHash": "6ad36b20"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.53.1 — 2026-10-28
+
+### ♻️ Refactoring
+
+- Lead release-kit's function names with a transitive verb (#1137)
+
+  Renames the functions in `release-kit`'s source and tests so that each name starts with a transitive verb that states its action, such as `releasePrepareTargets` to `prepareReleaseTargets`, `releaseWorkflow` to `renderReleaseWorkflow`, and `topologicalSort` to `sortTopologically`. The exports of `.` and `./config` stay the same.
+
+## 0.53.0 — 2026-10-27
+
+### 🎉 Features
+
+- Adds the time saved to the line that `nmr-compile` prints when it skips an unchanged package, as in `Skipping build, saved ~2.1s.`, when the skipped emit took at least a second. (#1112)
+- Adds `build skipped as unchanged` to the verdict line of a compile that hits the build cache, followed by the saved time when the recorded emit took at least a second, which nmr prints in a quiet run as well. (#1113)
+- Adds a `stated` field to the `--json` record of a passing command that stated its own outcome, such as `{"kind":"build-unchanged","savedMs":2100}`, which records the saving whatever its size. (#1113)
+- Removes the 7-day `maturityPeriod` from the shared policy that `defineConfig` in `@williamthorsen/nmr/taze` supplies, so that `nmr upgrade` waits for the `minimumReleaseAge` set in `pnpm-workspace.yaml` (or pnpm's default) and no longer withholds releases that pnpm already resolves for other packages. (#1129)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that nmr reported a short or negative duration for a command's run, a delegated run, or a remote lock wait when the system clock was adjusted during that span. (#1112)
+- Fixes the issue that `nmr-fmt` never formatted a file whose name starts with `-` and rejected `--` as an unknown option, by making `nmr-fmt` accept `--` before its pathspecs and pass `--` to Prettier before the file list. (#1130)
+
+### ♻️ Refactoring
+
+- Apply the naming conventions to nmr-core's identifiers (#1125)
+
+  Renames the identifiers in nmr-core to follow the naming conventions, including the exported option keys of `updateManagedFile` and `writeFileWithCheck`, which change from `dryRun` and `overwrite` to `isDryRun` and `shouldOverwrite`, and the constant `GIT_OUTPUT_LIMIT`, which becomes `GIT_OUTPUT_LIMIT_BYTES`. Updates the call sites in nmr, release-kit, and v11y-check to the new names.
+
 ## 0.52.0 — 2026-10-24
 
 ### 🎉 Features

package/README.md

@@ -4,19 +4,7 @@
 
 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.52.0 (2026-10-24)
-
-### 🎉 Features
-
-- Adds a 📡 glyph before the host name in the rich-output `nmr` verdicts that name a host, for a passed, failed, or recalled run, which leaves plain output and verdicts reading `on this tree` unchanged. (#1105)
-- Adds the root command `lint:workflows` and its `nmr-actionlint` bin, which lint `.github/workflows/` with actionlint 1.7.12, including its shellcheck pass over each `run:` block with shellcheck 0.11.0, using binaries that nmr downloads on first use, checks against pinned SHA-256 checksums, and caches under `node_modules/.cache/nmr-tools/`. (#1107)
-- Adds `lint:workflows` to the root `check`, `check:strict`, and `root:check` composites, which makes those composites and `nmr ci` fail on any actionlint finding in a repo that has workflows, need access to `github.com` on their first run, and fail on any platform other than macOS or Linux on x64 or arm64. (#1107)
-
-### 🐛 Bug fixes
-
-- Fixes the issue that a delegated `nmr` command could not find a bin that the branch added to a workspace package, because the host's `pnpm install --frozen-lockfile` did not link new bins when the lockfile was unchanged. (#1108)
-<!-- /section:release-notes -->
+<!-- section:release-notes --><!-- /section:release-notes -->
 
 ## Installation
 

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

@@ -1,5 +1,5 @@
 import type { Writable } from 'node:stream';
-import type { OutputStyle } from '@williamthorsen/nmr-core';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type TreeSnapshot } from './check-cache.js';
 import { type RunPlan } from './invocation.js';
 import type { NmrConfig } from './types.js';

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

@@ -1,3 +1,4 @@
+import { startTimer } from '@williamthorsen/nmr-core';
 import { formatMisplacedNoCacheWarning, isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { recordDelegatedPass } from "./check-cache-delegation.js";
@@ -10,6 +11,7 @@ import { VERSION } from "./invocation.js";
 import { resolveChannel } from "./output-channel.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
 import { runSteps } from "./runner.js";
+import { splitSegments } from "./shell-syntax.js";
 export function openGate(options) {
     const { command, config, env, monorepoRoot, passthrough, stderr, style } = options;
     if (!isCacheableCommand(config.checkCache, command)) {
@@ -83,9 +85,9 @@ export async function runGated(plan) {
             stdout.write(plan.overrideNotice);
         }
         const runOptions = { ...plan.runOptions, env: addLockEnv(plan.runOptions.env ?? env, lock) };
-        const startedAtMs = Date.now();
-        const { exitCode, retainedOutput } = await runSteps(plan.steps, anchorDir, runOptions);
-        const durationMs = Date.now() - startedAtMs;
+        const readElapsedMs = startTimer();
+        const { exitCode, retainedOutput, statedOutcomes } = await runSteps(plan.steps, anchorDir, runOptions);
+        const durationMs = readElapsedMs();
         if (exitCode === 0 && gate !== undefined) {
             await recordPass({
                 anchorDir,
@@ -105,9 +107,12 @@ export async function runGated(plan) {
                 stderr,
             });
         }
+        const stated = readOwnStatement(plan.ownSteps, statedOutcomes);
         return {
             exitCode,
-            outcome: exitCode === 0 ? { outcome: 'passed', durationMs } : { outcome: 'failed', durationMs, exitCode },
+            outcome: exitCode === 0
+                ? { outcome: 'passed', durationMs, ...(stated !== undefined && { stated }) }
+                : { outcome: 'failed', durationMs, exitCode },
         };
     }
     finally {
@@ -168,6 +173,13 @@ async function readGate(plan) {
         snapshot,
     };
 }
+function readOwnStatement(ownSteps, statedOutcomes) {
+    const [ownStep] = ownSteps;
+    if (ownSteps.length !== 1 || ownStep?.kind !== 'opaque' || splitSegments(ownStep.command).length !== 1) {
+        return undefined;
+    }
+    return statedOutcomes?.get(ownStep);
+}
 async function recallPass(plan, gate) {
     const { anchorDir, command, context, env, stderr } = plan.invocation;
     const { monorepoRoot } = context;

package/dist/esm/commands/build-output.d.ts

@@ -44,6 +44,11 @@ export declare function hasExpectedBuildOutput(packageDir: string, outdir: strin
  * current one.
  */
 export declare function readBuildDigest(packageDir: string): Promise<string | undefined>;
+/**
+ * Returns how long the emit took, in milliseconds, for the build that recorded `digest`, or `undefined` when no
+ * duration was recorded for that digest.
+ */
+export declare function readEmitDuration(packageDir: string, digest: string): Promise<number | undefined>;
 /**
  * Resolves the absolute path of a package's build-cache file, one entry in the shared store. The package
  * directory is the entry's scope, so the store keys the file to it and packages sharing a hoisted
@@ -54,6 +59,12 @@ export declare function readBuildDigest(packageDir: string): Promise<string | un
  * to the digest. Changing any of them leaves every entry on disk unreachable.
  */
 export declare function resolveBuildCachePath(packageDir: string): string;
+/**
+ * Resolves the absolute path of the entry that records how long a package's last emit took. It is a separate file in
+ * the build-cache entry's scope, so that a value varying from run to run never enters the digest that
+ * `readBuildDigest` returns.
+ */
+export declare function resolveEmitDurationPath(packageDir: string): string;
 /**
  * Resolves the two scratch directories through which a build publishes: `staging`, which the emit is written to,
  * and `previous`, which the outgoing output is renamed aside to. Both are siblings of the emit directory, so a
@@ -80,3 +91,5 @@ export declare function resolveScratchDirs(emitDir: string): ScratchDirs;
  * the pre-rebuild binary keeps the old fingerprint and rebuilds on the next run.
  */
 export declare function resolveToolchainFingerprint(packageDir: string, selfDir?: string): Promise<string>;
+/** Records how long the emit took for the build whose digest is `digest`. */
+export declare function writeEmitDuration(packageDir: string, digest: string, emitMs: number): Promise<void>;

package/dist/esm/commands/build-output.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
-import { findPackageRoot, readCacheEntry, resolveCacheEntryPath } from '@williamthorsen/nmr-core';
+import { findPackageRoot, readCacheEntry, readGuardedCacheEntry, resolveCacheEntryPath, writeGuardedCacheEntry, } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import { readPackageJson } from "../helpers/package-json.js";
 export const DEFAULT_ENTRY_GLOBS = ['src/**/*.{ts,tsx}'];
@@ -27,6 +27,10 @@ export function hasExpectedBuildOutput(packageDir, outdir, entryPoints) {
 export async function readBuildDigest(packageDir) {
     return readCacheEntry(resolveBuildCachePath(packageDir));
 }
+export async function readEmitDuration(packageDir, digest) {
+    const entry = await readGuardedCacheEntry(resolveEmitDurationPath(packageDir), digest, isEmitDurationEntry);
+    return entry?.emitMs;
+}
 export function resolveBuildCachePath(packageDir) {
     const absolutePackageDir = path.resolve(packageDir);
     return resolveCacheEntryPath({
@@ -36,6 +40,15 @@ export function resolveBuildCachePath(packageDir) {
         extension: '.hash',
     });
 }
+export function resolveEmitDurationPath(packageDir) {
+    const absolutePackageDir = path.resolve(packageDir);
+    return resolveCacheEntryPath({
+        tool: BUILD_CACHE_TOOL,
+        scopeDir: absolutePackageDir,
+        slug: path.basename(absolutePackageDir),
+        extension: '.duration.json',
+    });
+}
 export function resolveScratchDirs(emitDir) {
     const parent = path.dirname(emitDir);
     const name = path.basename(emitDir);
@@ -53,6 +66,22 @@ export async function resolveToolchainFingerprint(packageDir, selfDir = SELF_DIR
     }
     return readPackageJson(selfDir).version ?? '';
 }
+export async function writeEmitDuration(packageDir, digest, emitMs) {
+    const entry = { emitMs };
+    try {
+        await writeGuardedCacheEntry(resolveEmitDurationPath(packageDir), digest, entry);
+    }
+    catch {
+    }
+}
+function isEmitDurationEntry(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'emitMs' in value &&
+        typeof value.emitMs === 'number' &&
+        Number.isFinite(value.emitMs) &&
+        value.emitMs >= 0);
+}
 function isSameDir(left, right) {
     return resolveRealPath(left) === resolveRealPath(right);
 }

package/dist/esm/commands/build.js

@@ -2,11 +2,13 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, readCacheEntry, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, readCacheEntry, startTimer, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import { NMR_GLYPHS } from "../glyphs.js";
 import { resolveConfigPath } from "../helpers/config-path.js";
-import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, } from "./build-output.js";
+import { formatSaving } from "../helpers/duration.js";
+import { writeStatedOutcome } from "../stated-outcome.js";
+import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, readEmitDuration, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, writeEmitDuration, } from "./build-output.js";
 import { assertSupportedTypeScript, formatDiagnostics, getCompiler, loadCompiler } from "./compiler.js";
 import { isWithin, rewriteSpecifiers } from "./rewrite-specifiers.js";
 import { resolveTsconfigChain } from "./tsconfig-chain.js";
@@ -37,8 +39,11 @@ export async function buildPackage(packageDir, options) {
         await discardScratchDirs(resolveScratchDirs(emitDir));
         return;
     }
+    const readEmitMs = startTimer();
     const emittedFileCount = await emitPackage(packageDir, entryPoints, outdir);
+    const emitMs = readEmitMs();
     await writeCacheEntry(cachePath, currentHash);
+    await writeEmitDuration(packageDir, currentHash, emitMs);
     console.info(formatGlyphLine(NMR_GLYPHS, options.style, 'package', `${path.basename(packageDir)}: ${describeEmit(emittedFileCount, outdir)}`));
 }
 export async function computeBuildHash(packageDir, files, emitConfig, toolchain) {
@@ -184,7 +189,11 @@ async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cach
     const currentHash = await computeBuildHash(packageDir, files, emitConfig, toolchain);
     if (previousHash === currentHash) {
         if (isOutputPresent) {
-            console.info(`${STATUS_GLYPHS[style].skipped.text} ${packageName}: No changes detected. Skipping build.`);
+            const savedMs = await readEmitDuration(packageDir, currentHash);
+            await writeStatedOutcome(process.env, { kind: 'build-unchanged', ...(savedMs !== undefined && { savedMs }) });
+            const saving = formatSaving(savedMs ?? 0);
+            const savingClause = saving === undefined ? '' : `, ${saving}`;
+            console.info(`${STATUS_GLYPHS[style].skipped.text} ${packageName}: No changes detected. Skipping build${savingClause}.`);
             return { changed: false, currentHash };
         }
         console.info(formatGlyphLine(NMR_GLYPHS, style, 'package', `${packageName}: Build output is missing. Rebuilding.`));

package/dist/esm/commands/clean.d.ts

@@ -1,6 +1,6 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
- * Removes a package's build output and the build-cache entry that describes it, so the package does not keep
+ * Removes a package's build output and the build-cache entries that describe it, so the package does not keep
  * any state that would make the next build skip. Removal is idempotent: An already-clean package is a silent
  * no-op.
  */

package/dist/esm/commands/clean.js

@@ -11,13 +11,14 @@ import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.
 import { runCommand } from "../runner.js";
 import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
-import { resolveBuildCachePath } from "./build-output.js";
+import { resolveBuildCachePath, resolveEmitDurationPath } from "./build-output.js";
 const CLEAN_COMMAND = 'clean';
 const BUILT_IN_CLEAN = 'nmr-clean';
 const OUTPUT_ROOT = 'dist';
 export async function cleanPackage(packageDir, style) {
     await rm(path.resolve(packageDir, OUTPUT_ROOT), { recursive: true, force: true });
     await rm(resolveBuildCachePath(packageDir), { force: true });
+    await rm(resolveEmitDurationPath(packageDir), { force: true });
     console.info(formatGlyphLine(NMR_GLYPHS, style, 'clean', `${path.basename(packageDir)}: Removed build output and cache.`));
 }
 export async function runClean(cwd, style) {

package/dist/esm/commands/fmt.d.ts

@@ -6,7 +6,8 @@ export type FormatMode = 'check' | 'write';
  *
  * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
  * than passed along, since git would read it as a pathspec matching nothing and the run would report
- * success over an empty selection.
+ * success over an empty selection. Every argument after `--` is a pathspec, even one that starts
+ * with `-`.
  */
 export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
 /** @internal */

package/dist/esm/commands/fmt.js

@@ -13,7 +13,7 @@ import { resolveFormatTargets } from "./format-targets.js";
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default.config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
-const USAGE = 'Usage: nmr-fmt (--check | --write) [--no-cache] [pathspec...]';
+const USAGE = 'Usage: nmr-fmt (--check | --write) [--no-cache] [--] [pathspec...]';
 const MODE_ARGS = {
     check: ['--check'],
     write: ['--list-different', '--write'],
@@ -79,7 +79,11 @@ function parseFmtArgs(argv) {
     let mode;
     let shouldBypassCache = false;
     const pathspecs = [];
-    for (const arg of argv) {
+    for (const [index, arg] of argv.entries()) {
+        if (arg === '--') {
+            pathspecs.push(...argv.slice(index + 1));
+            break;
+        }
         if (arg === '--no-cache') {
             shouldBypassCache = true;
             continue;
@@ -147,6 +151,7 @@ export function runPrettier(options) {
             ? []
             : ['--cache', '--cache-strategy', 'content', '--cache-location', cacheLocation]),
         ...MODE_ARGS[mode],
+        '--',
     ];
     let firstFailureStatus = 0;
     for (const batch of batchWithinBudget(files, budgetBytes)) {

package/dist/esm/commands/run-vitest.js

@@ -7,6 +7,7 @@ import { reportError } from '@williamthorsen/nmr-core';
 import { findMonorepoRoot as findMonorepoRootOrNothing } from '@williamthorsen/nmr-core/workspace';
 import { describeSignalExitCode } from "../child-process.js";
 import { isObject } from "../helpers/type-guards.js";
+import { omitOutcomeFile } from "../stated-outcome.js";
 const VITEST_PACKAGE = 'vitest';
 const SUPPORTED_VITEST_RANGE = '>=4.0.0 <6';
 const CONFIG_EXTENSIONS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
@@ -18,6 +19,7 @@ export function runNmrVitest(argv, cwd = process.cwd()) {
     }
     const result = spawnSync(process.execPath, [cli.cliPath, ...chooseVitestConfigArgs(argv, cwd)], {
         cwd,
+        env: omitOutcomeFile(process.env),
         stdio: 'inherit',
     });
     if (result.error) {

package/dist/esm/delegate-host.js

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import { Writable } from 'node:stream';
-import { reportError } from '@williamthorsen/nmr-core';
+import { reportError, startTimer } from '@williamthorsen/nmr-core';
 import { NO_CACHE_ENV_VAR, resolveRunId, writeDebugNote } from "./check-cache.js";
 import { buildChildEnv, buildRemoteEnv } from "./child-env.js";
 import { resolveDelegationTarget } from "./delegation-target.js";
@@ -111,7 +111,7 @@ async function delegate(options) {
     const { invocation, remoteEnv, target } = options;
     const { command, context, cwd, env, parsedArgs, stderr, stdout } = invocation;
     const listedHosts = target.hosts.join(', ');
-    const startedAtMs = Date.now();
+    const readElapsedMs = startTimer();
     const snapshot = createSnapshot(cwd, env);
     if (!snapshot.ok && snapshot.isUnsupported) {
         if (target.source === 'flag') {
@@ -144,7 +144,7 @@ async function delegate(options) {
             stdout: createTee(stdout, retained.stdout),
         })
         : { ok: false, message: 'could not snapshot the working tree', output: snapshot.reason, waitedMs: 0 };
-    const durationMs = Date.now() - startedAtMs - result.waitedMs;
+    const durationMs = readElapsedMs() - result.waitedMs;
     const ran = {
         kind: 'ran',
         durationMs,

package/dist/esm/remote-run.js

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { startTimer, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
 import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
@@ -74,18 +74,18 @@ export async function runRemotely(options) {
     const marker = `__NMR_DELEGATE_${nonce}__`;
     const statusFile = `.git/nmr-run-status-${nonce}`;
     const passes = [];
-    let waitStartedAtMs;
+    let readWaitedMs;
     let waitedMs = 0;
     let failure;
     const demultiplexer = createSessionDemultiplexer({
         marker,
         onRecord(record) {
             if (record.kind === 'waiting') {
-                waitStartedAtMs ??= Date.now();
+                readWaitedMs ??= startTimer();
                 stderr.write(`${formatDelegationWaitingLine(record.holder, host)}\n`);
             }
-            else if (record.kind === 'locked' && waitStartedAtMs !== undefined) {
-                waitedMs = Date.now() - waitStartedAtMs;
+            else if (record.kind === 'locked' && readWaitedMs !== undefined) {
+                waitedMs = readWaitedMs();
             }
             else if (record.kind === 'failed') {
                 failure = record;

package/dist/esm/remote-snapshot.js

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+import { GIT_OUTPUT_LIMIT_BYTES } from '@williamthorsen/nmr-core';
 export function createSnapshot(cwd, env) {
     const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
     if (!toplevelResult.ok) {
@@ -69,7 +69,7 @@ function copyIndex(source, destination) {
     fs.utimesSync(destination, atime, mtime);
 }
 function runGit(args, cwd, env) {
-    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT });
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT_BYTES });
     if (result.error !== undefined) {
         return { ok: false, error: result.error.message };
     }

package/dist/esm/runner.d.ts

@@ -1,4 +1,5 @@
 import { type RunCommandOptions, type RunCommandResult } from './child-process.js';
+import { type StatedOutcome } from './stated-outcome.js';
 import type { Step } from './steps.js';
 /** What a step list needs to run. Each step's channels follow its kind, so the caller chooses none of them. */
 export type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
@@ -14,6 +15,8 @@ export interface RunStepsResult {
      * at least one to capture.
      */
     retainedOutput?: RetainedOutput;
+    /** The outcome that each foreground opaque step stated, absent unless a step that exited 0 stated one. */
+    statedOutcomes?: Map<Step, StatedOutcome>;
 }
 /**
  * Runs a step list in order and resolves once one fails or all have run, implementing the `&&` semantics that
@@ -33,6 +36,10 @@ export interface RunStepsResult {
  * Returns a bounded copy of what the list's own commands wrote, so that a caller can retain it. Only opaque
  * steps contribute: A structural step is another nmr process reporting for the subtree beneath it, and its
  * output is that subtree's to account for.
+ *
+ * Each foreground opaque step is handed a file of its own in `NMR_OUTCOME_FILE`, through which an nmr bin states its
+ * outcome. Every other step runs without the variable, as does a step whose value would have been inherited from an
+ * ancestor, so that a statement reaches only the list that handed out its file.
  */
 export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<RunStepsResult>;
 /**

package/dist/esm/runner.js

@@ -1,10 +1,16 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 import process from 'node:process';
+import { writeDebugNote } from "./check-cache.js";
 import { describeSignalExitCode, startSpawned, } from "./child-process.js";
 import { createOutputRecorder } from "./helpers/createOutputRecorder.js";
 import { isTerminal, resolveChannel, resolveInheritedChannel } from "./output-channel.js";
+import { omitOutcomeFile, OUTCOME_FILE_ENV_VAR, readStatedOutcome } from "./stated-outcome.js";
 export async function runSteps(steps, cwd, options) {
     const resolvedOptions = {
         ...options,
+        env: omitOutcomeFile(options.env ?? process.env),
         quiet: options.quiet === true,
         stdout: options.stdout ?? process.stdout,
         stderr: options.stderr ?? process.stderr,
@@ -15,6 +21,8 @@ export async function runSteps(steps, cwd, options) {
     const runningChildren = new Set();
     let receivedSignal;
     let foregroundExitCode = 0;
+    const statedOutcomes = new Map();
+    let outcomeDir;
     function forwardSignal(signal) {
         receivedSignal ??= signal;
         for (const child of runningChildren)
@@ -26,6 +34,24 @@ export async function runSteps(steps, cwd, options) {
         void started.result.finally(() => runningChildren.delete(started.child));
         return started;
     }
+    async function runForeground(step) {
+        if (step.kind !== 'opaque') {
+            return { result: await launch(step, resolvedOptions).result };
+        }
+        outcomeDir ??= await mkdtemp(path.join(os.tmpdir(), 'nmr-outcome-'));
+        const outcomeFile = path.join(outcomeDir, `${steps.indexOf(step)}.json`);
+        const env = { ...resolvedOptions.env, [OUTCOME_FILE_ENV_VAR]: outcomeFile };
+        const started = launch(step, { ...resolvedOptions, env });
+        const result = await started.result;
+        if (result.exitCode !== 0) {
+            return { result };
+        }
+        const parentPids = [process.pid, ...(started.child.pid === undefined ? [] : [started.child.pid])];
+        const statedOutcome = await readStatedOutcome(outcomeFile, parentPids, (reason) => {
+            writeDebugNote(`ignoring the outcome that a step stated: ${reason}`, resolvedOptions.env, resolvedOptions.stderr);
+        });
+        return { result, ...(statedOutcome !== undefined && { statedOutcome }) };
+    }
     function flushEndedBackgroundRuns() {
         for (const run of backgroundRuns) {
             if (run.result === undefined || run.isFlushed)
@@ -48,8 +74,10 @@ export async function runSteps(steps, cwd, options) {
                 backgroundRuns.push(startBackgroundRun(step, resolvedOptions, launch));
                 continue;
             }
-            const result = await launch(step, resolvedOptions).result;
+            const { result, statedOutcome } = await runForeground(step);
             flushEndedBackgroundRuns();
+            if (statedOutcome !== undefined)
+                statedOutcomes.set(step, statedOutcome);
             if (step.kind === 'opaque') {
                 if (result.stderr === undefined || result.stdout === undefined) {
                     isCaptureWhole = false;
@@ -75,9 +103,15 @@ export async function runSteps(steps, cwd, options) {
     finally {
         process.off('SIGINT', forwardSignal);
         process.off('SIGTERM', forwardSignal);
+        if (outcomeDir !== undefined)
+            await rm(outcomeDir, { force: true, recursive: true });
     }
     const exitCode = selectExitCode(foregroundExitCode, receivedSignal, backgroundRuns);
-    return { exitCode, ...composeRetainedOutput(parts, isCaptureWhole) };
+    return {
+        exitCode,
+        ...composeRetainedOutput(parts, isCaptureWhole),
+        ...(statedOutcomes.size > 0 && { statedOutcomes }),
+    };
 }
 export async function runCommand(command, cwd, options) {
     return runSpawned({ args: [], file: command, input: 'inherit', shouldUseShell: true }, cwd, options);
@@ -113,7 +147,7 @@ function composeRetainedOutput(parts, isCaptureWhole) {
     };
 }
 function buildBackgroundEnv(options) {
-    const env = options.env ?? process.env;
+    const { env } = options;
     const shouldForceColor = isTerminal(options.stdout) && (env['NO_COLOR'] ?? '') === '' && env['FORCE_COLOR'] === undefined;
     return shouldForceColor ? { ...env, FORCE_COLOR: '1' } : env;
 }

package/dist/esm/stated-outcome.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Names the file in which an nmr bin states its own outcome to the nmr process that runs it. nmr sets it for each
+ * opaque step and removes it from every other process that it starts.
+ */
+export declare const OUTCOME_FILE_ENV_VAR = "NMR_OUTCOME_FILE";
+/**
+ * An outcome that a bin states about its own run, which a passing verdict reports in its detail slot.
+ *
+ * `build-unchanged` is a build-cache hit. Its `savedMs` is the emit time recorded for the current inputs, whatever
+ * its size, and is absent when none was recorded; whether a saving is worth naming belongs to rendering.
+ */
+export interface StatedOutcome {
+    kind: 'build-unchanged';
+    savedMs?: number;
+}
+/**
+ * Returns the environment without `NMR_OUTCOME_FILE`, for a process that is not the one to which the file was handed,
+ * so that it cannot state an outcome for the step that runs it.
+ */
+export declare function omitOutcomeFile(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Reads the outcome that a step stated in `filePath`, or `undefined` when it stated none. A record that cannot be
+ * read as a stated outcome is reported to `onRejection` and treated as none, so that a bin from another nmr version
+ * cannot break the verdict.
+ *
+ * A record is accepted only from a process whose parent is one of `parentPids`: the process that handed out the file,
+ * or the shell that it spawned for the step. A shell running a single command either replaces itself with it or runs
+ * it as its child, so the step's own bin passes either way. Where the shell replaces itself, a process that the
+ * command starts passes too; a process two levels below the command does not.
+ */
+export declare function readStatedOutcome(filePath: string, parentPids: readonly number[], onRejection: (reason: string) => void): Promise<StatedOutcome | undefined>;
+/**
+ * Writes the outcome into the file that `NMR_OUTCOME_FILE` names, with this process's parent as the one that it is
+ * stated to, and does nothing when the variable is unset. The statement is advisory: A write that fails leaves the
+ * verdict reading as it would without one.
+ */
+export declare function writeStatedOutcome(env: NodeJS.ProcessEnv, outcome: StatedOutcome): Promise<void>;

package/dist/esm/stated-outcome.js

@@ -0,0 +1,60 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import process from 'node:process';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isObject } from "./helpers/type-guards.js";
+export const OUTCOME_FILE_ENV_VAR = 'NMR_OUTCOME_FILE';
+export function omitOutcomeFile(env) {
+    return Object.fromEntries(Object.entries(env).filter(([name]) => name !== OUTCOME_FILE_ENV_VAR));
+}
+export async function readStatedOutcome(filePath, parentPids, onRejection) {
+    let text;
+    try {
+        text = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return undefined;
+        }
+        onRejection(`could not read ${filePath}: ${describeError(error)}`);
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        onRejection(`${filePath} does not contain JSON`);
+        return undefined;
+    }
+    if (!isStatedOutcome(value)) {
+        onRejection(`${filePath} does not contain a stated outcome that this nmr knows`);
+        return undefined;
+    }
+    if (!parentPids.includes(value.parentPid)) {
+        onRejection(`${filePath} was written by a process whose parent is not one of ${parentPids.join(', ')}`);
+        return undefined;
+    }
+    return value.savedMs === undefined ? { kind: value.kind } : { kind: value.kind, savedMs: value.savedMs };
+}
+export async function writeStatedOutcome(env, outcome) {
+    const filePath = env[OUTCOME_FILE_ENV_VAR];
+    if (filePath === undefined || filePath === '') {
+        return;
+    }
+    try {
+        const record = { ...outcome, parentPid: process.ppid };
+        await writeFile(filePath, JSON.stringify(record));
+    }
+    catch {
+    }
+}
+function isMissingFileError(error) {
+    return isObject(error) && error['code'] === 'ENOENT';
+}
+function isStatedOutcome(value) {
+    if (!isObject(value) || value['kind'] !== 'build-unchanged' || !Number.isSafeInteger(value['parentPid'])) {
+        return false;
+    }
+    const savedMs = value['savedMs'];
+    return savedMs === undefined || (typeof savedMs === 'number' && Number.isFinite(savedMs) && savedMs >= 0);
+}

package/dist/esm/taze.d.ts

@@ -3,8 +3,8 @@ import type { CheckOptions } from 'taze';
  * A taze configuration.
  *
  * Every property admits `undefined` explicitly, unlike `Partial<CheckOptions>`, which rejects it under
- * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `maturityPeriod`, so the type
- * has to allow it.
+ * `exactOptionalPropertyTypes`. Passing `undefined` is how a consumer clears `mode`, so the type has to allow
+ * it.
  */
 export type TazeConfig = {
     [K in keyof CheckOptions]?: CheckOptions[K] | undefined;
@@ -12,7 +12,7 @@ export type TazeConfig = {
     /**
      * Maturity period in days for each package pattern, read by `nmr-taze` rather than by taze. A key is a package
      * name in which `*` matches any run of characters, and the first key that matches a package decides its period.
-     * Every other dependency keeps `maturityPeriod`.
+     * Every other dependency keeps `maturityPeriod` or, while that is unset, pnpm's `minimumReleaseAge`.
      */
     packageMaturityPeriod?: Record<string, number> | undefined;
 };
@@ -20,10 +20,12 @@ export type TazeConfig = {
  * Builds a taze configuration from nmr's shared upgrade policy and a repo's own settings.
  *
  * Any property that the caller supplies wins, including `0` and an explicit `undefined`, which clears nmr's
- * default and hands the setting back to taze. Clearing `maturityPeriod` restores taze's inheritance of pnpm's
- * `minimumReleaseAge`, which only applies while it is unset. Clearing `mode` yields taze's own `'default'`, which
- * follows each declared range; passed through as `undefined`, it would overwrite taze's default and leave no
- * valid range to search.
+ * default and hands the setting back to taze. Clearing `mode` yields taze's own `'default'`, which follows each
+ * declared range; passed through as `undefined`, it would overwrite taze's default and leave no valid range to
+ * search.
+ *
+ * The policy leaves `maturityPeriod` unset, because taze inherits pnpm's `minimumReleaseAge` only while it is
+ * unset. A repo that sets it replaces pnpm's period.
  *
  * The merge is shallow, which suits a policy of scalar defaults. A nested default would clobber rather
  * than merge, so adding one means revisiting this.

package/dist/esm/taze.js

@@ -1,6 +1,5 @@
 const SHARED_POLICY = {
     includeLocked: true,
-    maturityPeriod: 7,
     mode: 'minor',
 };
 export function defineConfig(config) {

package/dist/esm/verdict.d.ts

@@ -2,6 +2,7 @@ import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReplayLine } from './check-cache-entries.js';
 import type { ReportFormat } from './report-format.js';
+import type { StatedOutcome } from './stated-outcome.js';
 /**
  * The ceiling to which a rendered verdict, its newline included, is held.
  *
@@ -46,6 +47,7 @@ export type VerdictOutcome = {
 } & ({
     outcome: 'passed';
     durationMs: number;
+    stated?: StatedOutcome;
 } | {
     outcome: 'failed';
     durationMs: number;

package/dist/esm/verdict.js

@@ -5,7 +5,7 @@ import { formatDuration, formatSaving } from "./helpers/duration.js";
 export const VERDICT_LINE_LIMIT_BYTES = 512;
 export function renderVerdict(verdict, style) {
     const { marker, phrase } = describeOutcome(verdict, style);
-    const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? '');
+    const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? renderStated(verdict) ?? '');
     const detailClause = detail === '' ? '' : ` — ${detail}`;
     return clampToBytes(`${marker} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
 }
@@ -74,6 +74,13 @@ function renderReplay(verdict) {
     const lines = verdict.replay.map((line) => `${line.scope}: ${line.command}: ${line.excerpt}`);
     return `${REPLAY_MARKER} ${lines.join('; ')}`;
 }
+function renderStated(verdict) {
+    if (verdict.outcome !== 'passed' || verdict.stated === undefined) {
+        return undefined;
+    }
+    const saving = formatSaving(verdict.stated.savedMs ?? 0);
+    return saving === undefined ? 'build skipped as unchanged' : `build skipped as unchanged, ${saving}`;
+}
 function flattenDetail(detail) {
     return detail.replaceAll(/[\r\n]+/gu, ' ').trim();
 }

package/docs/reporting.md

@@ -6,6 +6,8 @@ The verdict line and its four outcomes are shown in the [README](../README.md#wh
 
 A recalled pass also includes an excerpt of the run that it recalls, if that run left one; see [Replaying a skipped run's output](check-cache.md#replaying-a-skipped-runs-output).
 
+A pass also includes what the command stated about its own run, if the command is an nmr bin that states one, such as `nmr-compile` on a build-cache hit: `PASS nmr-core: compile: passed in 0.3s — build skipped as unchanged, saved ~2.1s`. The line names the saving under the same rule as a recalled pass. Because the bin states it through [`NMR_OUTCOME_FILE`](#reserved-environment-variables) rather than through its output, a quiet run reports it too.
+
 The scope is the directory to which the command's registry belongs: a package's own directory, or the monorepo root. Durations and ages truncate and show at most two units, so a check that passed 119.9 seconds ago reports `1m 59s ago` and never `2m ago`.
 
 Verdicts nest. A composite reports, and so does every command into which it expands; a `:pre` or `:post` hook reports nothing of its own, since the command that it wraps already reports for the chain, though a hook that delegates to a named command reports under that name. A `-R` or `-F` invocation reports nothing either; every scope to which it fans out reports instead. A cold repo-wide `nmr ci` in this package's own monorepo uses 26 verdict lines to report a run that prints roughly 250.
@@ -38,7 +40,7 @@ Every object contains `command`, `scope`, and `outcome`, and then the fields tha
 
 | `outcome`  | Also contains                                                                                                           |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `passed`   | `durationMs`                                                                                                            |
+| `passed`   | `durationMs`, and `stated` when the command stated its own outcome, such as `{"kind":"build-unchanged","savedMs":2100}` |
 | `failed`   | `durationMs`, `exitCode`                                                                                                |
 | `recalled` | `ageMs`, `savedMs`, and `replay` when the skip has excerpts to [replay](check-cache.md#replaying-a-skipped-runs-output) |
 | `no-op`    | `reason`, one of `empty-override`, `empty-workspace`, or `noop-override`                                                |
@@ -72,6 +74,8 @@ Because the format is nmr's own reporting, and nmr does not tell the commands th
 
 `NMR_ENTRY_CHAIN` is nmr's own as well. It lists the commands that the current run has entered and the directories in which it entered them, and nmr passes it to every process that it starts, so that a process re-entering a command already running in its directory fails instead of repeating without end; see [self-referential entries](scripts.md#three-tier-override-system). Do not set it: nmr reports a value that it cannot read and exits 1.
 
+`NMR_OUTCOME_FILE` is nmr's own as well. nmr sets it for each command that it runs through the shell, naming a file of that step's own, in which an nmr bin states its outcome; nmr reads the file once the step exits 0 and removes it afterwards. nmr accepts the statement only from a command whose own script is a single shell command, and only from a process that names as its parent, in the record, nmr or the shell that nmr spawned for the step. A bin therefore cannot speak for a chain or for a hook around it. Whether a process that the step's command starts can state one depends on the shell: Where the shell runs the command as its child, as Debian's and Ubuntu's /bin/sh does, only the command itself can state an outcome; where the shell replaces itself with the command, as bash does, a process that the command starts can state one too, so a wrapper script that runs a bin as its child speaks for its step. `nmr-vitest` withholds the variable from the suite that it runs, so that a test exercising a bin cannot speak for the `test` step. nmr also removes the variable from every other process that it starts. Do not set it: nmr replaces an inherited value, and ignores a record that it cannot read.
+
 ### Output style
 
 `--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error, and nmr exits with code 1, whichever source named it. The flag outranks the variable, and both accept `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.

package/docs/upgrades.md

@@ -40,11 +40,13 @@ export default defineConfig({
 });
 ```
 
-`defineConfig` supplies nmr's shared upgrade policy, so a repo's config contains only what is specific to that repo. The policy is a seven-day quarantine on brand-new releases and the pair of settings that report a dependency pinned to an exact version: Locked dependencies are included, and the range searched is `minor`. Any setting that a repo's config declares wins over nmr's default. Passing `undefined` clears a default rather than falling back to it; that is how a config hands the quarantine policy back to `pnpm-workspace.yaml`'s `minimumReleaseAge`. Clearing `mode` hands the range back to the upgrade tool's own default, which follows the range that each dependency declares.
+`defineConfig` supplies nmr's shared upgrade policy, so a repo's config contains only what is specific to that repo. The policy is the pair of settings that report a dependency pinned to an exact version: Locked dependencies are included, and the range searched is `minor`. Any setting that a repo's config declares wins over nmr's default. Passing `undefined` clears a default rather than falling back to it. Clearing `mode` hands the range back to the upgrade tool's own default, which follows the range that each dependency declares.
+
+The policy does not set `maturityPeriod`, so the quarantine on brand-new releases is pnpm's: The upgrade tool applies the `minimumReleaseAge` of `pnpm-workspace.yaml`, or pnpm 11's default when the file does not set one (under pnpm 10 or earlier, a workspace that does not set it is not quarantined), and the packages that its `minimumReleaseAgeExclude` lists skip the quarantine. A `maturityPeriod` in a repo's config replaces pnpm's period.
 
 Everything the [taze configuration](https://github.com/antfu-collective/taze#config-file) accepts is accepted here, with five exceptions that the upgrade tool does not read from any config file at all: `concurrency`, `githubActions`, `ignoreOtherWorkspaces`, `nodeVersion`, and `requestTimeout`. The tool's CLI writes a default for each of them over whatever the config declares ([taze#317](https://github.com/antfu-collective/taze/issues/317)), so the command line is the only place they can be set. nmr's ReadyUp kit warns when a repo's config declares one, and [request timeout](#request-timeout) below shows how to set it instead.
 
-> **Note:** Only this file activates nmr's upgrade policy. A repo without one gets neither the release quarantine nor the settings that report a dependency pinned to an exact version, and `nmr upgrade` reports nothing in a repo using pnpm's `savePrefix: ''`. nmr's ReadyUp kit warns when the file is missing.
+> **Note:** Only this file activates nmr's upgrade policy. A repo without one does not get the settings that report a dependency pinned to an exact version, and `nmr upgrade` reports nothing in a repo using pnpm's `savePrefix: ''`. nmr's ReadyUp kit warns when the file is missing.
 
 Two consequences of the `minor` range mode declared by the policy:
 
@@ -53,13 +55,13 @@ Two consequences of the `minor` range mode declared by the policy:
 
 ### Per-package maturity periods
 
-`packageMaturityPeriod` gives the packages that match a pattern a quarantine of their own, in days. Every other dependency keeps `maturityPeriod`. taze applies one maturity period to a whole run, so `nmr upgrade` runs it once for each entry and once more for every other dependency, each run headed on stderr by the patterns and the period that it covers. The command exits with the first non-zero exit code among the runs.
+`packageMaturityPeriod` gives the packages that match a pattern a quarantine of their own, in days. Every other dependency keeps `maturityPeriod` or, while that is unset, pnpm's `minimumReleaseAge`. taze applies one maturity period to a whole run, so `nmr upgrade` runs it once for each entry and once more for every other dependency, each run headed on stderr by the patterns and the period that it covers. The command exits with the first non-zero exit code among the runs.
 
 ```ts
 import { defineConfig } from '@williamthorsen/nmr/taze';
 
 export default defineConfig({
-  // Propose first-party releases after one day, and third-party ones after the policy's seven.
+  // Propose first-party releases after one day, and third-party ones after pnpm's `minimumReleaseAge`.
   packageMaturityPeriod: {
     '@williamthorsen/*': 1,
     readyup: 1,

package/docs/utilities.md

@@ -12,7 +12,7 @@ nmr-actionlint
 
 ## `nmr-clean`
 
-Remove a package's build output (`dist`) and its `nmr-compile` cache entry, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
+Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
 
 ```bash
 nmr-clean
@@ -32,6 +32,8 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 
 **What busts the cache.** The key folds each input's content and path, the emit options, the resolved TypeScript version, and a fingerprint of the nmr running the build -- its own build digest in a workspace checkout, its package version otherwise. Upgrading nmr in a consuming repo therefore rebuilds every package that nmr compiles, and an edit to nmr's own build sources rebuilds each sibling once nmr itself has been rebuilt. A build of nmr's own package folds the version rather than the digest, which is the cache entry that this build is about to write.
 
+**What a skip reports.** Each build records how long its emit took, in a second entry beside the key (`.duration.json`), held to the key under which it was recorded. A skip names that time as the saving, `No changes detected. Skipping build, saved ~2.1s.`, when the recorded emit took at least a second and was recorded for the current inputs; otherwise the line ends at `Skipping build.` The time covers compiling and publishing the output, the work that a skip avoids, and not the hashing that a skip also does. The duration is a separate entry, so it never changes the key. Run through nmr, a skip also appears on the compile verdict line, `passed in 0.3s — build skipped as unchanged, saved ~2.1s`, which a quiet run still prints; see [what nmr reports](reporting.md#what-nmr-reports).
+
 `typescript` is an optional peer dependency (`>=5.7.0 <7`), needed only by `nmr-compile`; the consuming repo provides it, and `nmr-compile` run without it fails with an error naming the peer and the version that it requires. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling exists because TypeScript 7 does not include a compiler API: Its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must use explicit `.ts` or `.tsx` extensions for them to be rewritten.
 
 ```bash
@@ -49,13 +51,14 @@ A repo's own copy must be Prettier 3.0.0 or later. The design requires `--ignore
 ```bash
 nmr-fmt --check
 nmr-fmt --write packages/nmr
+nmr-fmt --check -- -lead.js
 ```
 
 ### File selection
 
 `fmt` and `fmt:check` format the files that git reports: tracked files, plus untracked files that git does not ignore. Prettier reads `.gitignore` and `.prettierignore` from the working directory alone, so a pattern in `packages/<pkg>/.gitignore` never applies to a run started at the monorepo root. Because git knows the whole hierarchy, including `.git/info/exclude` and `core.excludesFile`, and every `.prettierignore` in the tree is discovered from the repository root, package-level exclusions apply from any directory as well.
 
-A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec for which git lists no file both fail it. Running outside a git repository fails rather than reporting a clean run.
+A file that git ignores is never formatted, even when named directly. Because trailing arguments are git pathspecs rather than Prettier flags, `nmr fmt:check packages/nmr` narrows the run, while an unrecognized option and a pathspec for which git lists no file both fail it. Every argument after `--` is a pathspec, even one that starts with `-`, so an unrecognized option fails the run only before `--`. Running outside a git repository fails rather than reporting a clean run.
 
 `nmr-fmt` drops paths that the index names but the filesystem does not have (a file deleted but not yet staged), submodule gitlinks, and symlinks whatever they point at, before calling Prettier, which rejects a symlink named explicitly. It also skips a path that it is denied access to, such as a `.envrc` that a sandbox shields, and names each one on stderr, so that a check that passes does not hide a file that it never read. A pathspec whose every match is skipped still counts as matched: The run passes and names the skipped paths on stderr, so that a pre-commit hook passing only staged symlinks or a submodule bump does not fail. Any other failure to stat a listed path fails the run, with an error that names the path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.52.0",
+  "version": "0.53.1",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -79,23 +79,23 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.13.6",
-    "@williamthorsen/toolbelt.errors": "0.8.4",
-    "@williamthorsen/toolbelt.filesystem": "0.9.4",
-    "glob": "13.0.6",
+    "@williamthorsen/nmr-core": "0.14.0",
+    "@williamthorsen/toolbelt.errors": "0.9.0",
+    "@williamthorsen/toolbelt.filesystem": "0.10.0",
+    "glob": "14.0.2",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
     "taze": "21.3.0",
     "unconfig": "7.5.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.7.0",
-    "@williamthorsen/toolbelt.vitest": "0.12.0",
+    "@williamthorsen/toolbelt.testing": "0.8.0",
+    "@williamthorsen/toolbelt.vitest": "0.13.0",
     "esbuild": "0.28.2",
-    "readyup": "0.43.0",
+    "readyup": "0.44.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.4",
+    "vite": "8.3.5",
     "vitest": "5.0.5",
     "yaml": "2.9.1"
   },