feat(pm): refuse a doomed pnpm run version rehearsal with a diagnosis instead of hanging (#9555) (#9620)

A local version rehearsal in an agent container never terminates: every clone
descends from a shallow checkout, so each `.changeset/*.md` resolves to the
parentless shallow boundary and @changesets/git deepens-and-retries in a loop
with no attempt limit — against a remote that gains it nothing while exiting 0.
Measured here: no remote 0.009s, local shallow origin 0.36s, `--unshallow` from
that source 0.275s, all exit 0, none gaining a commit. It reads as slow progress
and cost ~2.5h before diagnosis.

`scripts/pm/release-rehearsal-clone.mjs` diagnoses the clone (mutating nothing)
and refuses with the mechanism plus both measured remedies; `--prepare` repairs a
throwaway clone (offline scaffold, tree hash asserted identical, plus the base
branch `changeset status` needs) and refuses to fabricate commits in anything
with a network remote. Its `--self-test` pins both directions and the wiring, and
runs in lint.yml. docs/releases-maintenance.md now prescribes the rehearsal with
the preflight in it.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

.github/workflows/lint.yml

@@ -293,6 +293,37 @@ jobs:
       - name: Governed-merges audit self-test
         run: pnpm check:pm-governed-merges
 
+      # Release-rehearsal clone preflight self-test (#9555). A local
+      # `pnpm run version` rehearsal — the prescribed verification route for
+      # every release-machinery change — HANGS FOREVER in an agent container:
+      # every clone descends from a shallow checkout, so each `.changeset/*.md`
+      # resolves to the parentless shallow boundary, and @changesets/git answers
+      # a parentless add-commit by deepening and retrying in a loop with no
+      # attempt limit — against a remote that gains it nothing and exits 0 while
+      # doing so. Measured cost before diagnosis: ~2.5 h over two attempts,
+      # because full CPU with no output reads as slow progress, not as a hang.
+      # `scripts/pm/release-rehearsal-clone.mjs` is the refusal that turns that
+      # into a one-second diagnosis, plus the repair for a throwaway clone.
+      #
+      # What runs HERE is the self-test, not the live check: the live check
+      # judges whatever clone it is pointed at, and a CI checkout's depth is the
+      # workflow's business rather than a verdict this job can hold. The
+      # self-test pins BOTH directions on real git fixtures — the trapped shape
+      # refuses, while a healthy tree AND a merely-shallow one whose changesets
+      # sit after the boundary pass untouched (the predicate is the parentless
+      # add-commit, never `--is-shallow-repository` alone) — and it pins the
+      # WIRING, so unlinking the script from docs/releases-maintenance.md or
+      # from this step reddens instead of going quiet. Temp-dir fixtures, no
+      # network, ~1.7 s.
+      #
+      # Invoked as `node` rather than through a `pnpm check:*` alias: that alias
+      # belongs in root package.json, which is declared territory of the
+      # @changesets/cli v3 migration lane (#9465) while it runs. Same shape as
+      # check-links.yml's ADR-link step, and dispatch-gates.mjs derives gate
+      # families from either spelling.
+      - name: Release-rehearsal clone preflight self-test
+        run: node scripts/pm/release-rehearsal-clone.mjs --self-test
+
       # Docs/skills authoring guard (#2035 / ADR-0059): TS code blocks in
       # Markdown/MDX are not type-checked or ESLinted, so skills/ and
       # content/docs/ can drift back to teaching the bare `: Page = {}` literal

docs/releases-maintenance.md

@@ -214,6 +214,47 @@ node scripts/check-objectui-pin-fresh.mjs --ref v17.0.0 --json
   the bump is that ratchet's only trigger), then re-source the Console section with
   `scripts/objectui-range.mjs`.
 
+## Rehearsing the version pass (throwaway clone)
+
+Release-machinery changes are verified by replaying a real version pass in a
+**throwaway clone** — never in a working checkout, because the pass consumes
+`.changeset/*.md`, rewrites every `packages/*/CHANGELOG.md` and moves the
+`package.json` versions. Run the preflight first; it is the difference between a
+one-second diagnosis and a hang that looks like progress:
+
+```bash
+git clone /home/user/objectstack /tmp/rehearsal && cd /tmp/rehearsal
+node scripts/pm/release-rehearsal-clone.mjs --prepare .   # refuse, or repair
+pnpm install --frozen-lockfile
+pnpm run version                                          # the rehearsal itself
+```
+
+### Why the preflight exists (#9555)
+
+A clone taken inside an agent container is **shallow** (it descends from a
+shallow checkout, and `.git/shallow` is inherited), and that breaks changesets in
+two places at once — same root cause, two entry points, and neither of them says
+so:
+
+| symptom | dies in | what you actually see |
+|---|---|---|
+| `changeset version` never finishes | `getCommitsThatAddFiles`: every changeset resolves to the parentless shallow boundary, so it deepens and retries in a loop with no attempt limit | full CPU, no output, clean `git status` — reads as slow progress; the first attempt was allowed to run 70 minutes |
+| `changeset status` cannot answer | `getDivergedCommit` (`git merge-base main HEAD`) — a clone of a container checkout has no local `main` at all | `Failed to find where HEAD diverged from "main"`, and the obvious workaround `--since origin/main` then exits 0 reporting **nothing**, which reads as "no packages to release" |
+
+Diagnosing that cost roughly two and a half hours the first time. The script
+carries the whole mechanism, the measurements and the two remedies in its
+header — `git fetch --unshallow` (10.2 s, +36 MB here, and it gives changelog
+links the *real* add-commits) or an offline two-commit scaffold that leaves the
+tree hash byte-identical. Run with no flags it only diagnoses and mutates
+nothing; `--prepare` repairs a throwaway clone and refuses to touch anything that
+looks like a real checkout. Its `--self-test` runs in `lint.yml` and pins both
+directions, so the refusal cannot rot into a guard that fires on everything or on
+nothing.
+
+**This is a local-rehearsal trap only.** `cut-rc.yml` and `release.yml` check out
+with `fetch-depth: 0`, so a real cut has full history and never enters that
+branch.
+
 ## Cutting a release
 
 Two routes, and the choice is not a preference — an rc and a GA release need