@entro314labs/release-kit 2.10.0 → 2.11.0

package/README.md

@@ -10,7 +10,7 @@
 [![downloads](https://img.shields.io/npm/dm/@entro314labs/release-kit?color=cb3837)](https://www.npmjs.com/package/@entro314labs/release-kit)
 [![unpacked size](https://img.shields.io/npm/unpacked-size/@entro314labs/release-kit?color=blueviolet)](https://www.npmjs.com/package/@entro314labs/release-kit?activeTab=code)
 [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#-requirements)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2022-339933?logo=node.js&logoColor=white)](#-requirements)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2024-339933?logo=node.js&logoColor=white)](#-requirements)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -127,7 +127,7 @@ Pin the URL to a tag, never `main`: piping an unpinned remote script into an int
 means whatever is at that URL runs against your repository and your credentials. `--sync` is
 the one thing that does not work this way — copying itself needs a file on disk.
 
-> **All five paths run the same file and need Node 22+.** That includes the Rust, Python and
+> **All five paths run the same file and need Node 24+.** That includes the Rust, Python and
 > Go projects: `release-kit` is a Node program regardless of what it is releasing.
 
 Zero-config works on the conventions below; add a [`release.config.json`](#️-configuration)
@@ -186,22 +186,23 @@ Prerelease bumps need `--preid` unless the current version already carries one t
 
 ### Flags
 
-| Flag                         | Effect                                                                        |
-| ---------------------------- | ----------------------------------------------------------------------------- |
-| `--only <steps>`             | Run only these steps, comma-separated.                                        |
-| `--skip <steps>`             | Run every step except these.                                                  |
-| `--commit`                   | Force the `commit` step on when a `steps` config removed it.                  |
-| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports.    |
-| `--yes`, `-y`                | Skip the confirmation prompt.                                                 |
-| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`.    |
-| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.                  |
-| `--notes <source>`           | Where notes come from: `auto`, `changelog`, `assistant`, `commits`, `github`. |
-| `--notes-file <path>`        | Write the resolved notes to a file for the next tool — see `notesFile`.       |
-| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                              |
-| `--assistant-model <name>`   | Model the assistant runs with.                                                |
-| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                     |
-| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.          |
-| `--help`, `-h`               | Full flag list.                                                               |
+| Flag                         | Effect                                                                                                                                                                                                                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--only <steps>`             | Run only these steps, comma-separated.                                                                                                                                                                                                                                                                         |
+| `--skip <steps>`             | Run every step except these.                                                                                                                                                                                                                                                                                   |
+| `--commit`                   | Force the `commit` step on when a `steps` config removed it.                                                                                                                                                                                                                                                   |
+| `--package`                  | Release the package in this directory, one of several in the repository: its `release.config.json`, manifest, changelog and publish; commits and working tree limited to the directory; tagged `<name>@<version>` unless `tagPrefix` is set. release-train passes it. Without it, a nested package is refused. |
+| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports.                                                                                                                                                                                                                                     |
+| `--yes`, `-y`                | Skip the confirmation prompt.                                                                                                                                                                                                                                                                                  |
+| `--preid <id>`               | Prerelease identifier for a `pre*` bump: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`.                                                                                                                                                                                                                   |
+| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.                                                                                                                                                                                                                                                   |
+| `--notes <source>`           | Where notes come from: `auto`, `changelog`, `assistant`, `commits`, `github`.                                                                                                                                                                                                                                  |
+| `--notes-file <path>`        | Write the resolved notes to a file for the next tool — see `notesFile`.                                                                                                                                                                                                                                        |
+| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                                                                                                                                                                                                                                                               |
+| `--assistant-model <name>`   | Model the assistant runs with.                                                                                                                                                                                                                                                                                 |
+| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                                                                                                                                                                                                                                                      |
+| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.                                                                                                                                                                                                                                           |
+| `--help`, `-h`               | Full flag list.                                                                                                                                                                                                                                                                                                |
 
 ### Linting commits
 
@@ -483,7 +484,9 @@ version the dead run already wrote: `minor` after a dead `minor` would release `
 from the commit `v1.1.0` already tags. Preflight refuses both shapes of that — the bump
 written but never committed, and the tag at `HEAD` that never reached the registry — and
 names the command that finishes the earlier release: `release-kit 1.1.0`, or no target, or
-`auto`.
+`auto`. With `"publish": null` there is no registry to ask, so a tag at `HEAD` that the
+remote does not have marks the unfinished release instead: a push that was refused is
+finished by `auto` too, and a relative bump over it is refused the same way.
 
 ### A release that was never published
 
@@ -751,6 +754,7 @@ release with the second bin in this package:
 
 ```sh
 release-train --dry-run     # plan + whole-train preflight, execute nothing
+release-train               # the same, then confirm and release (--yes without a terminal)
 ```
 
 `train.mjs` derives the dependency graph and publish order from the package manifests
@@ -758,13 +762,14 @@ release-train --dry-run     # plan + whole-train preflight, execute nothing
 the per-package worker, rewrites internal ranges, and refuses the whole train before
 anything mutates if any package would fail. A `train.config.json` declares only which
 directories are members. Design, configuration and the full pipeline are in
-[TRAIN.md](TRAIN.md). Prototype status: planning, preflight and `seed-tags` work;
-execution is not wired up yet.
+[TRAIN.md](TRAIN.md). A member that shares its git repository with other members is
+released with `--package`, so each keeps its own `<name>@<version>` tags and changelog.
 
 ## ⚙️ Configuration
 
-`release.config.json`, beside `package.json`. Every key is optional; unknown keys abort
-rather than being silently ignored.
+`release.config.json`, beside `package.json`. Every key is optional; unknown keys, and known
+keys holding the wrong type (a string where the table says array), abort rather than being
+silently ignored.
 
 | Key             | Default                | Meaning                                                                 |
 | --------------- | ---------------------- | ----------------------------------------------------------------------- |
@@ -1197,13 +1202,13 @@ npx @entro314labs/release-kit --sync ../project-a ../project-b
 ```
 
 It reports `installed`, `updated`, or `already up to date` per target, creates `scripts/`
-if missing, skips directories with no `package.json`, and warns when a target lacks the
-`release` npm script. It runs before any git resolution, so it works from anywhere,
+if missing, skips a directory that does not exist, and warns when a target with a
+`package.json` lacks the `release` npm script. It runs before any git resolution, so it works from anywhere,
 including a directory that is not a repository.
 
 ## 📋 Requirements
 
-- **Node 22+ — including for Rust, Python and Go projects.** `release-kit` is a Node
+- **Node 24+ — including for Rust, Python and Go projects.** `release-kit` is a Node
   program whatever it releases; there is no standalone binary.
 - `git`
 - `gh`, authenticated — only when creating GitHub releases
@@ -1219,7 +1224,7 @@ with the reasoning — are in [ROADMAP.md](ROADMAP.md).
 
 ```sh
 pnpm install
-pnpm test     # 188 tests, node --test, no framework
+pnpm test     # node --test, no framework
 pnpm check    # format + lint + tests, the same gate CI runs
 ```
 

package/TRAIN.md

@@ -9,24 +9,27 @@ Ships in this package as `train.mjs` — a second self-contained, `node:*`-only
 `release.mjs`, installed as the `release-train` bin. Same design contract as release-kit:
 readable, vendorable, zero dependencies.
 
-**Status: prototype.** Discovery, graph derivation, registry-aware change detection,
-cascade, planning, whole-train preflight, `seed-tags`, and the train summary work.
-Execution (running release-kit per package) is not implemented yet — `train` without
-`--dry-run` says so and exits. Three things the design below describes are not built
-either, and the plan does not claim them: taking `packages` from `pnpm-workspace.yaml` /
-`workspaces` when the config omits it (the config must list them today), and the two
-per-package authentication checks in the preflight table (publish CLI and `gh`), which
-each package's own release-kit run performs when execution lands.
+**Status.** Discovery, graph derivation, registry-aware change detection, cascade,
+planning, whole-train preflight, execution, `seed-tags` and the train summary work, for
+both topologies: a member alone in its repository releases exactly as standalone
+release-kit would, and a member sharing its repository with others releases with
+release-kit's `--package`. Not built yet, and not claimed:
+
+- Taking `packages` from `pnpm-workspace.yaml` / `workspaces` when the config omits it (the
+  config must list them today).
+- The two per-package authentication checks in the preflight table (publish CLI and `gh`)
+  run in each package's own release-kit preflight, at that package's turn — not up front.
 
 ```sh
+release-train                        # plan + preflight, confirm, release (--yes: no prompt)
 release-train graph                  # print the derived dependency graph and topo order
 release-train --dry-run              # full plan + whole-train preflight, execute nothing
-release-train --dry-run --all       # plan every member, not just changed ones
-release-train --dry-run <id>...     # plan these packages and their dependents
-release-train seed-tags             # baseline tags at each HEAD (--dry-run to preview)
-release-train --summary <path>      # write the train summary; --assistant drafts on top
-release-train --offline             # no network: registry checks skipped, tags not pushed
-release-train --config <path>       # config elsewhere than ./train.config.json
+release-train --all                  # every member, not just changed ones
+release-train <id>...                # these packages and their dependents
+release-train seed-tags              # baseline tags at each HEAD (--dry-run to preview)
+release-train --summary <path>       # write the train summary; --assistant drafts on top
+release-train --offline --dry-run    # no network: registry checks skipped, tags not pushed
+release-train --config <path>        # config elsewhere than ./train.config.json
 ```
 
 ## Problem
@@ -212,35 +215,67 @@ One failure anywhere aborts the entire train before any package releases. This i
 whole safety story for the meta-workspace, where no transaction exists — so it is
 deliberately strict: one dirty repo out of thirty blocks all thirty.
 
-**Execute.** In topo order, per package:
+**Execute.** After a confirmation prompt (`--yes` skips it, and is required without a
+terminal), in topo order, per package:
 
 1. Rewrite internal dependency ranges in this package's manifest to the versions its
-   dependencies just released, per `rangePolicy`. Skipped entirely for `workspace:`
+   dependencies just released, per `rangePolicy`, and commit that in the package's
+   repository as `chore(deps): move <name> <range>, …`. Skipped entirely for `workspace:`
    ranges — the package manager rewrites those at publish time, which is the preferred
-   setup inside a workspace.
-2. Run release-kit in the package directory: bump, changelog, release commit (the range
-   rewrite rides in it), tag, push, publish, GitHub release — whatever that package's
-   `steps` say.
+   setup inside a workspace. The lockfile governing the package (in its directory, or up
+   to its repository root for a workspace) records those ranges, so it is refreshed by the
+   tool that owns it — `pnpm install --lockfile-only`, `npm install --package-lock-only`,
+   both with `--ignore-scripts` — and rides in the same commit; a stale one would fail the
+   repository's next frozen install. A `yarn.lock` or `bun.lock` the train would have to
+   rewrite is refused in preflight instead of being committed stale. It is a commit of its
+   own, not part of release-kit's release commit: release-kit refuses a dirty tree unless
+   its `commit` step runs, and that step would stage everything and draft a message. The
+   separate commit is deterministic, and it gives a cascade-only release — a package whose
+   only change is its dependency — a commit for its notes to describe.
+2. Run release-kit — the `release.mjs` shipped beside `train.mjs`, one version for the
+   whole train — in the package directory with the planned version passed explicitly, so
+   release-kit releases exactly what the plan printed: bump, changelog, release commit,
+   tag, push, publish, GitHub release — whatever that package's `steps` say. A member
+   with `publish: false` runs with `--skip publish`; a Go member, which has no manifest
+   version, runs with `auto`; a member that shares its repository runs with `--package`
+   (below). `--assistant none` on the train is forwarded to every run.
 3. If any member still to come depends on this package: poll the registry
-   (`npm view name@version` or the ecosystem equivalent) until the new version is
-   visible or `registryWait.timeout` elapses. Registries have replication lag; a
-   dependent that publishes or installs too early fails spuriously.
-
-In a monorepo, step 2's commits per package would produce commit noise; there the
-orchestrator batches: all version/changelog/range writes land in one release commit, then
-tags, one push, then publishes in topo order with the same waits.
+   (`npm view name@version version`) every `registryWait.interval` seconds until the new
+   version is visible or `registryWait.timeout` elapses. Registries have replication lag;
+   a dependent that publishes or installs too early fails spuriously.
+
+The first failure stops the train and prints what was released, where it stopped, and
+what never started.
+
+**Several members in one repository.** release-kit on its own releases a whole
+repository and refuses a nested package. `--package` releases the directory it runs in
+instead: that directory's `release.config.json`, manifest, changelog, `verify` and publish;
+`git log`, `git status` and the commit step limited to it (`-- .`); and tags
+`<name>@<version>` unless the package's config sets `tagPrefix`. Each member gets its own
+release commit, tag and push, one after another in topological order — release-kit's steps
+unchanged, rather than batched into one commit, which would mean reordering them. A
+member at the repository root that shares it with nested members reads every commit in the
+repository, nested ones included. Inside a pnpm/npm workspace, internal ranges should be
+`workspace:` and the member's publish command `pnpm publish` (or its equivalent), which is
+what rewrites them into real ranges; a bare `npm publish` ships `workspace:` verbatim.
 
 **Report.** What released at which version, what was skipped and why, and — on failure —
 exactly which packages completed, so the resume story ("run it again") is verifiable.
 
 ## Failure and resume
 
-| Died at                            | State                                     | Re-run does                                           |
-| ---------------------------------- | ----------------------------------------- | ----------------------------------------------------- |
-| Preflight                          | Nothing mutated anywhere                  | Everything, after you fix the reported list           |
-| Mid-package (e.g. publish timeout) | That package partially released           | release-kit's own idempotency finishes it             |
-| Between packages                   | Earlier packages fully released           | Skips them (tag exists, version published), continues |
-| Registry wait timeout              | Dependency published, dependent untouched | Wait resumes; registry has had more time              |
+| Died at                                                                       | State                                     | Re-run does                                                                         |
+| ----------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
+| Preflight                                                                     | Nothing mutated anywhere                  | Everything, after you fix the reported list                                         |
+| Mid-package (e.g. publish timeout)                                            | That package partially released           | release-kit's own idempotency finishes it                                           |
+| Between packages                                                              | Earlier packages fully released           | Skips them (tag exists, version published), continues                               |
+| Registry wait timeout                                                         | Dependency published, dependent untouched | Wait resumes; registry has had more time                                            |
+| Between the version write and its commit (a lockfile refresh or hook failing) | That package's tree is dirty              | Preflight refuses the dirty tree; finish that package with release-kit, then re-run |
+
+A member whose `release.config.json` sets `requireGreen` is refused in preflight when the
+train commits to its repository before its turn (its own `chore(deps)` commit, or an
+earlier member's release in the same repository): CI cannot have passed that commit yet,
+so release-kit would stop the train there, after earlier members had released.
 
 The invariant throughout: at no point does a published package depend on an unpublished
 version, because dependencies always complete first.
@@ -315,12 +350,14 @@ Flag rules, mirroring release-kit's posture:
 - `--dry-run` composes with everything: it is always "show me, touch nothing".
 - `--offline` degrades honestly: the plan says which checks were skipped, and seed-tags
   skips npm members it cannot verify rather than guessing.
+- `--offline` plans only: a release publishes and waits on the registry, so `--offline`
+  without `--dry-run` is refused.
+- `--yes` skips the confirmation, as in release-kit; without a terminal it is required.
 - Deliberately absent: a `--bump <type>` override (forcing one bump across packages is
   lockstep by the back door; release one package explicitly instead and let derivation do
-  the rest) and a declared-order override (see Considered and declined). `--yes` arrives
-  with execution, matching release-kit. A `--json` plan output for CI is the one addition
-  under consideration — release-kit writes `$GITHUB_OUTPUT`, and the train's equivalent is
-  a machine-readable plan.
+  the rest) and a declared-order override (see Considered and declined). A `--json` plan
+  output for CI is the one addition under consideration — release-kit writes
+  `$GITHUB_OUTPUT`, and the train's equivalent is a machine-readable plan.
 
 ## Considered and declined
 
@@ -335,10 +372,10 @@ Flag rules, mirroring release-kit's posture:
 
 ## Open questions
 
-- **Monorepo commit batching** — the batched single-commit path shares release-kit's steps
-  but reorders when the commit happens; whether that is a release-kit flag
-  (`--no-commit`, commit handled by caller) or orchestrator-side sequencing needs a
-  decision before implementation.
+- **Batching a monorepo's releases into one commit** — each member releases with its own
+  commit today (see Execute). One commit for all of them is less history noise, but needs
+  release-kit to stop before its commit and resume after; worth it only if the per-member
+  commits turn out to be a problem.
 - **GitHub releases in a multi-package repo** — `gh release create` per tag works; whether
   the nested-package changelog path (`packages/x/CHANGELOG.md`) needs anything from
   release-kit beyond cwd-relative resolution needs verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",
@@ -49,8 +49,8 @@
     "release": "node release.mjs"
   },
   "devDependencies": {
-    "oxfmt": "^0.67.0",
-    "oxlint": "^1.82.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "semver": "^7.8.5"
   },
   "engines": {

package/release.mjs

@@ -220,6 +220,8 @@ Flags:
                        drafted Conventional Commits message instead of refusing to release
   --preid <id>         prerelease identifier (alpha, beta, rc, next, nightly, canary)
   --dist-tag <name>    override the npm dist-tag (default: derived from the version)
+  --package            release the package in this directory, one of several in the
+                       repository: its own tag (<name>@<version>), commits and publish
   --dry-run            print every step and execute nothing
   --yes, -y            skip the confirmation prompt
   --notes-file <path>  write the resolved release notes to a file for the next tool
@@ -286,7 +288,9 @@ const formatStatus = (porcelain) =>
     .join('\n')
 
 function abort(message, title = 'RELEASE ABORTED') {
-  console.log(`\n${red(bold(title))} — ${message}\n`)
+  // Through `say`: under `next`, stdout carries the version alone, and an abort captured by
+  // `$(...)` would otherwise become the "version".
+  say(`\n${red(bold(title))} — ${message}\n`)
   process.exit(1)
 }
 
@@ -297,9 +301,15 @@ function abort(message, title = 'RELEASE ABORTED') {
  * the real cause under a Node stack trace.
  */
 function abortMidRelease(commandLine) {
+  // A relative bump re-run as-is would count from the version this run already wrote, and
+  // preflight refuses it; what finishes the release is the version itself, or no target.
+  const rerun =
+    target && target !== 'auto' && BUMPS.has(target)
+      ? 're-run with no target (or `auto`)'
+      : 're-run the same command'
   abort(
     `\`${commandLine}\` failed — see its output above.\n\n` +
-      '  The release stopped partway through. Fix the cause and re-run the same command:\n' +
+      `  The release stopped partway through. Fix the cause and ${rerun}:\n` +
       '  the steps that already completed are detected and skipped.',
   )
 }
@@ -578,7 +588,7 @@ function commitsSinceLastTag(options) {
   // separator keeps multi-line messages parseable when splitting the log back apart.
   // %h first, then the author, then the message: the hash is what links each bullet back
   // to its commit, and the author is what says who is new here.
-  const raw = tryRead('git', ['log', `--format=%h%x1f%an%x1f%ae%x1f%B%x1e`, range]) ?? ''
+  const raw = tryRead('git', ['log', `--format=%h%x1f%an%x1f%ae%x1f%B%x1e`, range, ...SCOPE]) ?? ''
   const commits = raw
     .split('\u001E')
     .map((entry) => entry.trim())
@@ -1281,7 +1291,9 @@ function pushBranchAndTag(branchRef) {
   } catch (err) {
     const stderr = `${err.stderr ?? ''}`
     process.stderr.write(stderr)
-    if (!/atomic/i.test(stderr)) abortMidRelease(line)
+    // Only the capability refusal falls back. git's rejection of a ref also names atomic
+    // ("atomic push failed"), and that one must stop here.
+    if (!/does not support --atomic/i.test(stderr)) abortMidRelease(line)
   }
   warn(
     `${config.remote} does not support atomic pushes — sending the branch and tag in one ` +
@@ -1493,6 +1505,10 @@ function candidateSections(text, version) {
 /** The `## ` heading offsets in a changelog, in file order. */
 const sectionOffsets = (text) => [...text.matchAll(/^## .*$/gm)].map((m) => m.index)
 
+/** True when the changelog already has a `## [version]` heading, empty body or not. */
+const hasVersionHeading = (text, version) =>
+  new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)
+
 /**
  * Place a version's section where it belongs: above the first section whose version is
  * lower, rather than wherever the file happens to start.
@@ -1601,7 +1617,7 @@ function withChangelogLinks(text, links, tagPrefix = '') {
 function rollUnreleased(text, version, date) {
   // A heading for this version already exists — possibly with an empty body, which
   // `changelogSection` reports as absent. Rolling again would duplicate the heading.
-  if (new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)) return null
+  if (hasVersionHeading(text, version)) return null
 
   const heading = /^##\s+\[?Unreleased\]?[^\n]*$/im
   const match = heading.exec(text)
@@ -2187,7 +2203,16 @@ const VALUE_OPTIONS = new Set([
 ])
 
 /** Flags that take no value. With VALUE_OPTIONS, the whole vocabulary this file accepts. */
-const BOOLEAN_FLAGS = new Set(['--dry-run', '--yes', '-y', '--commit', '--help', '-h', '--sync'])
+const BOOLEAN_FLAGS = new Set([
+  '--dry-run',
+  '--yes',
+  '-y',
+  '--commit',
+  '--package',
+  '--help',
+  '-h',
+  '--sync',
+])
 
 /** The version or bump target: the only argument that is neither a flag nor a flag's value. */
 const positionals = []
@@ -2222,6 +2247,14 @@ if (positionals.length > 1) {
     : ''
   abort(`unexpected argument${extras.length > 1 ? 's' : ''}: ${extras.join(' ')}${hint}`)
 }
+// Only a pre* bump reads --preid. Anywhere else it was accepted and dropped, so
+// `auto --preid beta` released a stable version to the `latest` dist-tag.
+if (requestedPreid !== undefined && !target?.startsWith('pre')) {
+  abort(
+    `--preid only applies to prepatch, preminor, premajor and prerelease, not ${target ? `"${target}"` : 'a release with no target'}.\n` +
+      `  For a ${requestedPreid} prerelease: release-kit prerelease --preid ${requestedPreid}`,
+  )
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // SETUP
@@ -2230,26 +2263,89 @@ if (positionals.length > 1) {
 const root = tryRead('git', ['rev-parse', '--show-toplevel'])
 if (!root) abort('not inside a git repository')
 
-// A release is scoped to the repository: the version, the tag and the push all belong to
-// one git history, so the package released is the one at the git root. Refuse when invoked
-// from a nested package instead — silently releasing the parent is the worse outcome.
+/**
+ * A release is scoped to the repository: the version, the tag and the push all belong to
+ * one git history, so the package released is the one at the git root. `--package` scopes
+ * it to the working directory instead — one package among several in the repository, as
+ * release-train runs it. Its config, manifest, changelog, verify and publish are that
+ * directory's; the commits it reads and the working tree it checks are limited to the
+ * directory; and it tags `<name>@<version>` unless its config names a `tagPrefix`, so
+ * packages sharing a history keep separate tags.
+ */
+const packageMode = flag('--package')
+
+// Without --package, refuse a nested package rather than silently releasing the parent.
 const localManifest = resolve('package.json')
 const rootManifest = join(root, 'package.json')
-if (existsSync(localManifest) && localManifest !== rootManifest) {
+if (!packageMode && existsSync(localManifest) && localManifest !== rootManifest) {
   abort(
     `${relative(root, localManifest)} is a nested package, but a release covers the whole ` +
       `repository.\n\n  Running here would release ${
         existsSync(rootManifest) ? readJson(rootManifest).name : 'the repository root'
       } instead.\n` +
-      '  release-kit handles one package per repository; it does not release workspace members.',
+      '  To release this package on its own — its own tag, commits, changelog and publish —\n' +
+      '  run with --package (release-train does, for a repository holding several).',
   )
 }
-process.chdir(root)
+if (!packageMode) process.chdir(root)
+
+/** The pathspec a package release limits `git log`, `git status` and `git add` to. */
+const SCOPE = packageMode ? ['--', '.'] : []
 
 const userConfig = readUserConfig()
 const config = { ...DEFAULTS, ...userConfig }
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
+
+/**
+ * What each key has to hold. A known key with the wrong shape was accepted and then read as
+ * if it were right: `"steps": "tag,push"` ran no step at all and still reported a release,
+ * `"tagPrefix": null` tagged `null1.1.0`, and a string where an array belongs crashed with a
+ * TypeError after the tag was pushed.
+ */
+const isString = (value) => typeof value === 'string'
+const isStringOrNull = (value) => value === null || isString(value)
+const isStringArray = (value) => Array.isArray(value) && value.every(isString)
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value)
+const CONFIG_SHAPES = {
+  steps: [isStringArray, 'an array of step names'],
+  tagPrefix: [isString, 'a string'],
+  branch: [isStringOrNull, 'a string, or null'],
+  remote: [isString, 'a string'],
+  changelog: [isStringOrNull, 'a string, or null'],
+  versionFile: [
+    (v) => v === undefined || isStringOrNull(v) || isObject(v),
+    'a path, an object, or null',
+  ],
+  versionFiles: [
+    (v) => Array.isArray(v) && v.every((f) => isString(f) || (isObject(f) && isString(f.path))),
+    'an array of paths or { path, pattern } objects',
+  ],
+  publish: [
+    (v) => v === undefined || isStringOrNull(v) || isStringArray(v),
+    'a command, an array of commands, or null',
+  ],
+  commitMessage: [isString, 'a string'],
+  releaseTitle: [isString, 'a string'],
+  assets: [isStringArray, 'an array of paths'],
+  assistant: [(v) => isStringOrNull(v) || isObject(v), 'a name, an object, or null'],
+  notesFile: [isStringOrNull, 'a path, or null'],
+  versioning: [
+    (v) => ['conventional', 'always-patch', 'always-minor', 'always-major'].includes(v),
+    'one of conventional, always-patch, always-minor, always-major',
+  ],
+  notes: [isString, 'a string'],
+  hiddenTypes: [isStringArray, 'an array of commit types'],
+  ignoreCommits: [isStringArray, 'an array of regexes'],
+  verify: [isStringOrNull, 'a command, or null'],
+  requireGreen: [(v) => typeof v === 'boolean', 'true or false'],
+  hooks: [(v) => isObject(v) && Object.values(v).every(isString), 'an object of command strings'],
+}
+const misshapen = Object.entries(CONFIG_SHAPES)
+  .filter(([key, [valid]]) => !valid(config[key]))
+  .map(([key, [, expected]]) => `  ${key} must be ${expected}, not ${JSON.stringify(config[key])}`)
+if (misshapen.length)
+  abort(`release.config.json has keys of the wrong type:\n${misshapen.join('\n')}`)
 // A misspelled hook name is a hook that silently never runs, which is the failure mode
 // this file refuses everywhere else it takes a name.
 const unknownHooks = Object.keys(config.hooks ?? {}).filter((key) => !HOOKS.includes(key))
@@ -2430,6 +2526,19 @@ function versionFromLastTag() {
   return releaseTags()[0]?.version ?? null
 }
 
+// A package's tags are `<name>@<version>`, the scheme release-train reads, unless its
+// config names a prefix. Set before anything reads a tag.
+if (packageMode && !Object.hasOwn(userConfig, 'tagPrefix')) {
+  const name = manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null)
+  if (!name) {
+    abort(
+      '--package tags a release <name>@<version>, and no package name was found here.\n' +
+        '  Set "tagPrefix" in this package\'s release.config.json.',
+    )
+  }
+  config.tagPrefix = `${name}@`
+}
+
 const currentVersion = versionFile ? readVersionFrom(versionFile) : versionFromLastTag()
 if (versionFile && !currentVersion) {
   abort(`could not read a version from ${versionFile.path}`)
@@ -2443,7 +2552,10 @@ const goModule = existsSync('go.mod')
   ? (/^module\s+(\S+)/m.exec(readFileSync('go.mod', 'utf8'))?.[1] ?? null)
   : null
 const projectName =
-  manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
+  manifest?.name ??
+  (versionFile ? readNameFrom(versionFile) : null) ??
+  goModule ??
+  basename(process.cwd())
 
 /**
  * Manifests found beside the primary one that carry the same version. Detected only when
@@ -2716,9 +2828,35 @@ function versionShipped(v) {
  */
 function unfinishedRelease() {
   const [newest] = releaseTags()
-  if (!newest || versionShipped(newest.version) !== false) return null
+  if (!newest) return null
   const at = tryRead('git', ['rev-list', '-n', '1', newest.name])
-  return at && at === tryRead('git', ['rev-parse', 'HEAD']) ? newest : null
+  if (!at || at !== tryRead('git', ['rev-parse', 'HEAD'])) return null
+  const shipped = versionShipped(newest.version)
+  if (shipped === false) return { ...newest, missing: 'the registry' }
+  // With no registry to ask — `publish: null`, or one that could not answer — the push is
+  // the last step that leaves a mark to check. A tag at HEAD the remote does not have is a
+  // release that died before or during the push.
+  if (shipped === null && runs('push') && tagOnRemote(newest.name) === false) {
+    return { ...newest, missing: config.remote }
+  }
+  return null
+}
+
+/**
+ * Whether the remote has this tag: false only when it answered without it, null when it
+ * could not be asked.
+ *
+ * @param {string} name
+ * @returns {boolean | null}
+ */
+function tagOnRemote(name) {
+  try {
+    read('git', ['ls-remote', '--exit-code', '--tags', config.remote, `refs/tags/${name}`])
+    return true
+  } catch (err) {
+    // --exit-code exits 2 for "no matching refs"; anything else is the remote not answering.
+    return err.status === 2 ? false : null
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2735,6 +2873,8 @@ let autoBump = null
 
 /** The tag of a previous release this run is finishing rather than starting. */
 let resuming = null
+/** What that release never reached: the registry, or the remote. */
+let resumingMissing = null
 
 /**
  * A release tagged at HEAD that never reached the registry, found while resolving a
@@ -2751,7 +2891,7 @@ let unfinishedAtHead = null
  * ship a tree the tag does not describe; that work belongs in the next version, which is
  * what the shipped-tag baseline makes sure it is released as.
  */
-const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
+const wouldCommitMore = !!tryRead('git', ['status', '--porcelain', ...SCOPE]) && runs('commit')
 
 let version
 if (!target) {
@@ -2771,7 +2911,7 @@ if (!target) {
   }
   const pending = wouldCommitMore ? null : unfinishedRelease()
   if (pending) {
-    ;({ name: resuming, version } = pending)
+    ;({ name: resuming, version, missing: resumingMissing } = pending)
   } else {
     const { commits, lastTag } = commitsSinceLastTag({ shipped: true })
     if (!commits.length) {
@@ -2880,12 +3020,15 @@ function runHook(name) {
  */
 function dirtyPaths() {
   return (
-    (tryRead('git', ['status', '--porcelain']) ?? '')
+    (tryRead('git', ['status', '--porcelain', ...SCOPE]) ?? '')
       .split('\n')
       .map((line) => /^\s*\S{1,2}\s+(.+)$/.exec(line)?.[1]?.trim())
       .filter(Boolean)
       // A rename reads as "old -> new"; the new path is the one to stage.
       .map((path) => path.split(' -> ').at(-1))
+      // Porcelain paths are relative to the repository root; everything they are compared
+      // with and staged as is relative to the working directory, which --package moves.
+      .map((path) => relative(process.cwd(), join(root, path)))
   )
 }
 
@@ -2945,12 +3088,12 @@ if (autoBump) {
 }
 
 if (resuming) {
-  ok(`finishing ${resuming}: it was tagged and pushed, but never reached the registry`)
+  ok(`finishing ${resuming}: it was tagged, but never reached ${resumingMissing}`)
 }
 
 if (unfinishedAtHead) {
   fail(
-    `${unfinishedAtHead.name} is tagged at HEAD but never reached the registry, and a ` +
+    `${unfinishedAtHead.name} is tagged at HEAD but never reached ${unfinishedAtHead.missing}, and a ` +
       `${target} bump would release ${version} from the same commit and leave it that way.\n` +
       `       Finish it instead: re-run with no target, or with auto.`,
   )
@@ -3096,7 +3239,7 @@ if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0)
   ok(`releasing ${version} (no version file; the tag is the version)`)
 }
 
-const dirty = tryRead('git', ['status', '--porcelain'])
+const dirty = tryRead('git', ['status', '--porcelain', ...SCOPE])
 if (dirty === null) fail('could not read git status')
 else if (dirty && runs('commit')) {
   const entries = dirty.split('\n')
@@ -3779,6 +3922,16 @@ for (const asset of config.assets) {
   else fail(`asset ${asset} does not exist`)
 }
 
+/**
+ * Whether drafted notes still have to be filed in the changelog. A named source (`commits`,
+ * `assistant`) drafts even when the section exists — a resume, or one written by hand — and
+ * filing it again would duplicate the heading and commit past a reused tag.
+ */
+const draftedSectionMissing = () =>
+  !!config.changelog &&
+  existsSync(config.changelog) &&
+  !hasVersionHeading(readFileSync(config.changelog, 'utf8'), version)
+
 // Reusing a tag is the resume path, and a resume writes nothing. If this run would still
 // produce a commit, that commit moves HEAD past the tag and the release ends up tagged at
 // the wrong revision — which is silent until someone checks out the tag, and worse for the
@@ -3789,6 +3942,7 @@ const wouldCommit = [
   // The roll is computed whenever [Unreleased] is populated, because the notes come from
   // it either way; it is only written — and only becomes a commit — when the step runs.
   rolledChangelog && runs('changelog') && 'a changelog entry',
+  draftedNotes && runs('changelog') && draftedSectionMissing() && 'a drafted changelog section',
 ].filter(Boolean)
 if (taggedCommit && runs('tag') && wouldCommit.length) {
   fail(
@@ -3835,7 +3989,7 @@ let commitMessage = null
 let didStage = false
 if (dirty && runs('commit') && !dryRun) {
   step('Stage the working tree')
-  mutate('git', ['add', '--all'])
+  mutate('git', ['add', '--all', ...SCOPE])
   didStage = true
   commitMessage = assistant ? draftCommitMessage() : null
   if (!commitMessage) {
@@ -3951,7 +4105,7 @@ if (rolledChangelog && runs('changelog')) {
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
   else writeFileSync(config.changelog, linked(rolledChangelog))
   staged.push(config.changelog)
-} else if (runs('changelog') && draftedNotes && config.changelog && existsSync(config.changelog)) {
+} else if (runs('changelog') && draftedNotes && draftedSectionMissing()) {
   step(`Add the drafted ${version} section to ${config.changelog}`)
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
   else {

package/train.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 /**
- * release-train — orchestrated releases for interdependent packages, prototype.
+ * release-train — orchestrated releases for interdependent packages.
  *
- * Implements the read-only phases of TRAIN.md — discover → graph → detect changes →
- * cascade → plan → preflight — plus `seed-tags`, which establishes baseline release tags.
- * Execution (releasing via release-kit) is not implemented yet; `train` without
- * --dry-run says so and exits.
+ * Implements TRAIN.md's pipeline — discover → graph → detect changes → cascade → plan →
+ * preflight → execute → report — plus `seed-tags`, which establishes baseline release tags.
+ * Execution runs the release-kit beside this file once per package, in dependency order; a
+ * package that shares its git repository with other members runs with `--package`.
  *
+ *   train                    plan + preflight, confirm, release (--yes skips the prompt)
  *   train graph              print the derived dependency graph and topo order
  *   train --dry-run          full plan + whole-train preflight, execute nothing
- *   train --dry-run --all    plan every member, not just changed ones
- *   train --dry-run <id>...  plan these packages and their dependents
+ *   train --all              every member, not just changed ones
+ *   train <id>...            these packages and their dependents
  *   train seed-tags          create baseline tags at each repo's HEAD (--dry-run to preview)
- *   train --offline          skip network work (registry lookups, tag pushes)
+ *   train --offline          skip network work (registry lookups, tag pushes); dry runs only
  *   train --config <path>    config elsewhere than ./train.config.json
  *
  * Reads train.config.json in the working directory. Config declares membership and
@@ -29,7 +30,7 @@
  *   3. The cascade: a dependent of a releasing package joins with at least a patch.
  */
 
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import {
   existsSync,
   mkdtempSync,
@@ -40,7 +41,8 @@ import {
 } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { basename, dirname, join, relative, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Small utilities
@@ -206,6 +208,12 @@ export function loadConfig(configPath) {
   if (!RANGE_POLICIES.has(rangePolicy))
     fail(`rangePolicy must be one of: ${[...RANGE_POLICIES].join(', ')}`)
   const registryWait = { timeout: 300, interval: 5, ...config.registryWait }
+  for (const key of ['timeout', 'interval']) {
+    if (typeof registryWait[key] !== 'number' || !(registryWait[key] > 0))
+      fail(`registryWait.${key} must be a positive number of seconds`)
+  }
+  const extraWaitKeys = Object.keys(registryWait).filter((k) => k !== 'timeout' && k !== 'interval')
+  if (extraWaitKeys.length) fail(`unknown registryWait key: ${extraWaitKeys.join(', ')}`)
   const assistant = normalizeAssistant(config.assistant ?? null)
   if (assistant?.error) fail(assistant.error)
   const summaryFile = config.summaryFile ?? null
@@ -216,6 +224,8 @@ export function loadConfig(configPath) {
 
 const KNOWN_FLAGS = new Set([
   '--dry-run',
+  '--yes',
+  '-y',
   '--all',
   '--offline',
   '--config',
@@ -231,6 +241,7 @@ function parseArgs(argv) {
     command: null,
     ids: [],
     dryRun: false,
+    yes: false,
     all: false,
     offline: false,
     configPath: null,
@@ -251,6 +262,7 @@ function parseArgs(argv) {
       const normalized = normalizeAssistant(name)
       args.assistant = normalized?.error ? fail(normalized.error) : normalized
     } else if (arg === '--dry-run') args.dryRun = true
+    else if (arg === '--yes' || arg === '-y') args.yes = true
     else if (arg === '--all') args.all = true
     else if (arg === '--offline') args.offline = true
     else if (arg === '--help' || arg === '-h') args.help = true
@@ -263,6 +275,10 @@ function parseArgs(argv) {
     fail('--all and explicit package ids conflict — pass one or the other')
   if (args.command === 'graph' && (args.all || args.ids.length))
     fail('graph takes no package ids or --all')
+  // A release publishes and waits on the registry; neither is possible offline, and a
+  // train that skipped them would release dependents onto versions nobody can install.
+  if (args.offline && !args.dryRun && args.command === null)
+    fail('--offline cannot release — it skips the registry a train publishes to. Add --dry-run')
   return args
 }
 
@@ -371,8 +387,10 @@ export function discover(rootDir, config) {
       repoRelPath: repoDir ? relative(repoDir, dir) || '.' : null,
       publish: entry.publish !== false,
       branch: releaseConfig.branch === undefined ? 'main' : releaseConfig.branch,
-      // The prefix release-kit will tag with, and so the one its history is read under.
-      tagPrefix: releaseConfig.tagPrefix ?? 'v',
+      // The prefix release-kit will tag with, and so the one its history is read under;
+      // null when the package's config leaves it to the default (see tagPatternFor).
+      tagPrefix: releaseConfig.tagPrefix ?? null,
+      requireGreen: releaseConfig.requireGreen === true,
       ...manifest,
     })
   }
@@ -450,13 +468,12 @@ export function topoSort(orderEdges) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Tag scheme: the package's own `tagPrefix` (`v` unless its release.config.json says
- * otherwise) when the repo owns exactly one member, `<name>@<version>` when it owns
- * several — which keeps single-package repos identical to standalone release-kit.
+ * Tag scheme: the package's own `tagPrefix` when its release.config.json sets one;
+ * otherwise `v` when the repo owns exactly one member, and `<name>@` when it owns several
+ * — the defaults release-kit itself tags with, standalone and under `--package`.
  */
 export function tagPatternFor(member, repoMemberCount) {
-  if (repoMemberCount > 1) return { prefix: `${member.name}@`, glob: `${member.name}@*` }
-  const prefix = member.tagPrefix ?? 'v'
+  const prefix = member.tagPrefix ?? (repoMemberCount > 1 ? `${member.name}@` : 'v')
   return { prefix, glob: `${prefix}*` }
 }
 
@@ -759,6 +776,38 @@ function preflight({
 
   for (const item of plan) {
     const { member, next } = item
+    // A member sharing its repository releases under --package, tagged `<name>@`; with no
+    // name and no configured prefix release-kit would stop at this package's turn.
+    if ((repoMemberCounts.get(member.repoDir) ?? 1) > 1 && !member.name && !member.tagPrefix) {
+      failures.push(
+        `${item.id}: shares ${relative(rootDir, member.repoDir) || '.'} with other members but has no package name to tag with — set "tagPrefix" in its release.config.json`,
+      )
+    }
+    // requireGreen refuses a HEAD CI has not passed. The train moves this member's HEAD
+    // before its turn — its own deps commit, or an earlier member's release commit in the
+    // same repository — so the refusal would come mid-train, after others released.
+    const earlierInRepo = plan
+      .slice(0, plan.indexOf(item))
+      .some((other) => other.member.repoDir === member.repoDir)
+    if (member.requireGreen && (item.rewrites.some((r) => r.to) || earlierInRepo)) {
+      failures.push(
+        `${item.id}: its release.config.json sets requireGreen, and the train commits to its repository before its turn — CI cannot have passed that commit; turn requireGreen off for train releases`,
+      )
+    }
+    // Moving a range makes the lockfile that records it stale, and a frozen install in
+    // that repository's CI then fails. The train refreshes it — with the tool that owns it.
+    if (item.rewrites.some((r) => r.to)) {
+      const lock = findLockfile(member)
+      if (lock && !lock.tool) {
+        failures.push(
+          `${item.id}: ${lock.name} records the ranges the train rewrites, and the train cannot refresh it — use workspace: ranges or an npm/pnpm lockfile`,
+        )
+      } else if (lock && !toolAvailable(lock.tool)) {
+        failures.push(
+          `${item.id}: ${lock.name} has to be refreshed after its ranges move, and ${lock.tool} is not installed`,
+        )
+      }
+    }
     if (!member.version) {
       warnings.push(
         `${item.id}: no manifest version (${member.ecosystem}); current version must come from its last release tag`,
@@ -944,7 +993,7 @@ function seedTags({ members, repoMemberCounts, registry, dryRun, offline }) {
  * Markdown report of the whole train: every package with its version movement and why,
  * plus the dependency ripple — which changes pulled which dependents in. Deterministic
  * and buildable from the plan alone; per-package release notes stay per-package
- * (release-kit owns those). `mode` is 'planned' until execution exists.
+ * (release-kit owns those). `mode` says whether the rows were planned or released.
  */
 export function buildSummary(plan, { workspace, date, mode = 'planned' }) {
   const lines = [
@@ -1101,6 +1150,232 @@ function draftAnnouncement(assistant, summaryMarkdown) {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Execute — release-kit once per package, dependencies first
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The release-kit shipped beside this file. Not the one on PATH and not a copy vendored in
+ * each package: a train is one release, and one release-kit version runs all of it.
+ */
+const RELEASE_KIT = join(dirname(fileURLToPath(import.meta.url)), 'release.mjs')
+
+const DEPENDENCY_MAPS = ['dependencies', 'peerDependencies', 'optionalDependencies']
+
+/**
+ * Lockfiles that record dependency ranges, nearest first, with the command that brings one
+ * back into step with its manifest. `tool: null` is a lockfile the train will not guess a
+ * refresh for; preflight refuses it rather than committing it stale.
+ */
+const LOCKFILES = [
+  {
+    name: 'pnpm-lock.yaml',
+    tool: 'pnpm',
+    args: ['install', '--lockfile-only', '--ignore-scripts'],
+  },
+  {
+    name: 'package-lock.json',
+    tool: 'npm',
+    args: ['install', '--package-lock-only', '--ignore-scripts'],
+  },
+  {
+    name: 'npm-shrinkwrap.json',
+    tool: 'npm',
+    args: ['install', '--package-lock-only', '--ignore-scripts'],
+  },
+  { name: 'yarn.lock', tool: null },
+  { name: 'bun.lock', tool: null },
+  { name: 'bun.lockb', tool: null },
+]
+
+/** The lockfile governing a member: in its directory, or up to its repository root (a workspace). */
+function findLockfile(member) {
+  let { dir } = member
+  for (;;) {
+    const lock = LOCKFILES.find(({ name }) => existsSync(join(dir, name)))
+    if (lock) return { ...lock, dir, path: join(dir, lock.name) }
+    if (!member.repoDir || dir === member.repoDir || dir === dirname(dir)) return null
+    dir = dirname(dir)
+  }
+}
+
+function toolAvailable(tool) {
+  return spawnSync(tool, ['--version'], { stdio: 'ignore', timeout: 20_000 }).status === 0
+}
+
+/**
+ * A package.json with its internal ranges moved to the versions the train is releasing.
+ * Every map that names the dependency is rewritten from its own current range, and
+ * `workspace:` ranges are left to the package manager. Returns null when nothing changes —
+ * the rewrite of a resumed train is already committed.
+ *
+ * @param {string} text  the manifest as read
+ * @param {Map<string, string>} targets  dependency name → the version it releases
+ * @param {string} policy  rangePolicy
+ * @returns {{ text: string, changed: string[] } | null}
+ */
+export function rewriteManifest(text, targets, policy) {
+  const manifest = JSON.parse(text)
+  const changed = new Set()
+  for (const key of DEPENDENCY_MAPS) {
+    for (const [name, version] of targets) {
+      const current = manifest[key]?.[name]
+      if (current === undefined) continue
+      const next = rewriteRange(policy, current, version)
+      if (next === null || next === current) continue
+      manifest[key][name] = next
+      changed.add(`${name} ${next}`)
+    }
+  }
+  if (!changed.size) return null
+  const indent = /^\{\r?\n([ \t]+)"/.exec(text)?.[1] ?? '  '
+  return { text: `${JSON.stringify(manifest, null, indent)}\n`, changed: [...changed] }
+}
+
+/**
+ * The release-kit command line for one plan item. The version is always passed explicitly
+ * — release-kit then releases exactly what the plan printed — except for a package with no
+ * manifest version (Go), whose version only release-kit can read, from its tags.
+ */
+export function releaseArgs(item, { noAssistant = false } = {}) {
+  const args = [item.next ?? 'auto', '--yes']
+  // One member of several in its repository: release the directory, not the repository.
+  if (item.member.sharesRepo) args.push('--package')
+  // `publish: false` in the train config: versioned, tagged and released, never published.
+  if (!item.member.publish) args.push('--skip', 'publish')
+  // `--assistant none` is the one assistant value forwarded: a whole-train kill switch.
+  // Forcing a drafting tool onto packages that did not opt in stays impossible.
+  if (noAssistant) args.push('--assistant', 'none')
+  return args
+}
+
+const sleep = (seconds) =>
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, seconds * 1000)
+
+/**
+ * Poll until `name@version` is on the registry. A dependent released before its dependency
+ * is visible fails its own install or publish, and registries replicate with a lag.
+ */
+function waitForRegistry(name, version, { timeout, interval }) {
+  const deadline = Date.now() + timeout * 1000
+  for (;;) {
+    const found = spawnSync('npm', ['view', `${name}@${version}`, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 20_000,
+    })
+    if (found.status === 0) return true
+    if (Date.now() + interval * 1000 > deadline) return false
+    sleep(interval)
+  }
+}
+
+/**
+ * Release the plan, in order. Each package: move its internal ranges onto the versions
+ * just released and commit that, run release-kit, then — when a later package depends on
+ * it — wait for the registry to show it. The first failure stops the train; everything
+ * before it is fully released, and a re-run resumes (see TRAIN.md, Failure and resume).
+ *
+ * @returns {{ released: string[], failed: string | null, reason: string | null }}
+ */
+function executePlan(plan, { rangePolicy, registryWait, noAssistant, env = process.env }) {
+  const released = []
+  const nextById = new Map(plan.map((item) => [item.id, item.next]))
+  const stop = (item, reason) => ({ released, failed: item.id, reason })
+
+  for (const [index, item] of plan.entries()) {
+    const { member } = item
+    console.log(`\n━━ ${index + 1}/${plan.length} ${item.id} ${item.next ?? '(version from tag)'}`)
+
+    const targets = new Map(
+      item.rewrites
+        .filter((r) => r.to)
+        .map((r) => [plan.find((p) => p.id === r.dep).member.name, nextById.get(r.dep)]),
+    )
+    if (targets.size) {
+      const manifestPath = join(member.dir, member.manifestFile)
+      const rewritten = rewriteManifest(readFileSync(manifestPath, 'utf8'), targets, rangePolicy)
+      if (rewritten) {
+        writeFileSync(manifestPath, rewritten.text)
+        const paths = [member.manifestFile]
+        const lock = findLockfile(member)
+        if (lock?.tool) {
+          // pnpm looks for its workspace by walking up past the repository, and a meta-
+          // workspace root may carry a pnpm-workspace.yaml of its own. A lockfile with no
+          // workspace file beside it is standalone: refresh that one, not a parent's.
+          const args =
+            lock.tool === 'pnpm' && !existsSync(join(lock.dir, 'pnpm-workspace.yaml'))
+              ? [...lock.args, '--ignore-workspace']
+              : lock.args
+          const refresh = spawnSync(lock.tool, args, {
+            cwd: lock.dir,
+            env,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+          })
+          if (refresh.status !== 0) {
+            process.stderr.write(`${refresh.stdout}${refresh.stderr}`)
+            git(member.dir, ['checkout', '--', member.manifestFile], { allowFailure: true })
+            return stop(item, `\`${lock.tool} ${args.join(' ')}\` failed refreshing ${lock.name}`)
+          }
+          paths.push(relative(member.dir, lock.path))
+        }
+        const subject = `chore(deps): move ${rewritten.changed.join(', ')}`
+        const committed =
+          git(member.dir, ['add', '--', ...paths], { allowFailure: true }) !== null &&
+          git(member.dir, ['commit', '-m', subject, '--', ...paths], {
+            allowFailure: true,
+          }) !== null
+        if (!committed)
+          return stop(item, `could not commit the range rewrite in ${member.manifestFile}`)
+        console.log(`  ${subject}`)
+      }
+    }
+
+    const run = spawnSync(process.execPath, [RELEASE_KIT, ...releaseArgs(item, { noAssistant })], {
+      cwd: member.dir,
+      env,
+      stdio: 'inherit',
+    })
+    if (run.status !== 0) return stop(item, `release-kit exited with ${run.status ?? run.signal}`)
+    released.push(item.id)
+
+    const awaited = plan
+      .slice(index + 1)
+      .some((later) => later.rewrites.some((r) => r.dep === item.id))
+    if (awaited && member.ecosystem === 'npm' && member.publish && member.name && item.next) {
+      console.log(`  waiting for ${member.name}@${item.next} on the registry…`)
+      if (!waitForRegistry(member.name, item.next, registryWait)) {
+        return stop(
+          item,
+          `${member.name}@${item.next} was released but is not on the registry after ${registryWait.timeout}s`,
+        )
+      }
+    }
+  }
+  return { released, failed: null, reason: null }
+}
+
+function printExecution(plan, { released, failed, reason }) {
+  if (!failed) {
+    console.log(
+      `\nTrain released — ${released.length} package${released.length === 1 ? '' : 's'}: ${released.join(', ')}`,
+    )
+    return
+  }
+  const notStarted = plan
+    .map((item) => item.id)
+    .filter((id) => id !== failed && !released.includes(id))
+  console.log(`\nTRAIN STOPPED at ${failed}: ${reason}`)
+  if (released.length) console.log(`  released:    ${released.join(', ')}`)
+  console.log(`  stopped:     ${failed}`)
+  if (notStarted.length) console.log(`  not started: ${notStarted.join(', ')}`)
+  console.log(
+    '\n  Fix the cause and run the same command again: released packages are skipped, and the\n' +
+      `  one that stopped is finished by release-kit from wherever it got to.`,
+  )
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Output
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1165,16 +1440,18 @@ function printSeedResults(results, dryRun) {
     console.log(`\n${refusedOrErrored} member(s) refused or failed — see above.`)
 }
 
-const HELP = `release-train (prototype — read-only phases, seed-tags, and the train summary)
+const HELP = `release-train — release interdependent packages in dependency order
 
-  train graph               print the derived dependency graph and topo order
+  train                     plan, preflight, confirm, then release everything that changed
+  train --yes               the same without the confirmation prompt (required without a terminal)
   train --dry-run           plan + whole-train preflight, execute nothing
-  train --dry-run --all     plan every member
-  train --dry-run <id>...   plan these packages and their dependents
+  train --all               every member, not just the changed ones
+  train <id>...             these packages and their dependents
+  train graph               print the derived dependency graph and topo order
   train seed-tags           create baseline tags (add --dry-run to preview)
   train --summary <path>    write the train summary (markdown) here; overrides summaryFile
   train --assistant <name>  none (whole-train kill switch), auto, claude, codex
-  train --offline           skip network work (registry lookups, tag pushes)
+  train --offline           skip network work (registry lookups, tag pushes); dry runs only
   train --config <path>     config file (default ./train.config.json)
 `
 
@@ -1182,7 +1459,7 @@ const HELP = `release-train (prototype — read-only phases, seed-tags, and the
 // Main
 // ─────────────────────────────────────────────────────────────────────────────
 
-function main() {
+async function main() {
   const args = parseArgs(process.argv.slice(2))
   if (args.help) {
     console.log(HELP)
@@ -1209,6 +1486,7 @@ function main() {
     if (member.repoDir)
       repoMemberCounts.set(member.repoDir, (repoMemberCounts.get(member.repoDir) ?? 0) + 1)
   }
+  for (const member of members) member.sharesRepo = (repoMemberCounts.get(member.repoDir) ?? 0) > 1
   const registry = gatherRegistry(members, args.offline)
 
   if (args.command === 'seed-tags') {
@@ -1224,8 +1502,6 @@ function main() {
     return
   }
 
-  if (!args.dryRun) fail('execution is not implemented yet — run with --dry-run')
-
   const changes = new Map()
   for (const member of members) {
     if (!member.repoDir) continue
@@ -1259,18 +1535,37 @@ function main() {
   })
   printPlan(plan, result)
 
+  let execution = null
+  if (!args.dryRun && !result.failures.length && plan.length) {
+    if (!args.yes) {
+      if (!process.stdin.isTTY)
+        fail('no terminal to confirm on — pass --yes to release the plan above')
+      const readline = createInterface({ input: process.stdin, output: process.stdout })
+      const answer = await readline.question(
+        `\nRelease ${plan.length} package${plan.length === 1 ? '' : 's'} in this order? [y/N] `,
+      )
+      readline.close()
+      if (!/^y(es)?$/i.test(answer.trim())) fail('aborted — nothing was released')
+    }
+    execution = executePlan(plan, {
+      rangePolicy: config.rangePolicy,
+      registryWait: config.registryWait,
+      noAssistant: args.assistant === null,
+    })
+    printExecution(plan, execution)
+  }
+
   // Train summary: deterministic always; announcement drafted only when an assistant is
   // configured (or forced via --assistant) and never blocking. --assistant none is the
-  // whole-train kill switch — when execution lands it is also forwarded to every
-  // release-kit run, and it is the ONLY assistant value that is forwarded: forcing a
-  // drafting tool onto packages that did not opt in stays impossible by design.
+  // whole-train kill switch, and executePlan forwards it to every release-kit run.
   const summaryPath = args.summaryPath ?? config.summaryFile
   if (summaryPath) {
     const date = new Date().toISOString().slice(0, 10)
-    let summary = buildSummary(plan, {
+    const shipped = execution ? plan.filter((item) => execution.released.includes(item.id)) : plan
+    let summary = buildSummary(shipped, {
       workspace: basename(rootDir),
       date,
-      mode: 'planned (dry run)',
+      mode: execution ? 'released' : args.dryRun ? 'planned (dry run)' : 'planned, not released',
     })
     const assistant = resolveAssistant(
       args.assistant === undefined ? config.assistant : args.assistant,
@@ -1287,7 +1582,7 @@ function main() {
     console.log(`\nTrain summary written to ${summaryPath}`)
   }
 
-  process.exitCode = result.failures.length ? 1 : 0
+  process.exitCode = result.failures.length || execution?.failed ? 1 : 0
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main()
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main()