v2/main's version drifts from main — bump on v2/main before the milestone merge

[cliffhall]

Summary

v2/main has been stuck at 2.0.0 since the v2.0.0 release, while main (and npm latest) is at 2.2.0. Two releases have shipped without the develop branch's version ever moving.

Root cause

The version bump is created on the milestone-merge branch, which is cut from main — so it only ever exists downstream of v2/main, and nothing carries it back. It is not an off-by-one from a single missed step; it has happened at every release:

Commit	On main	On v2/main
dedee5af chore: 2.1.0	yes	no
27cd42b4 chore: 2.2.0	yes	no

v2/main ──────────────────────────────►  (stays 2.0.0)
              \
milestone-br   ├─ merge v2/main
(cut from main)└─ chore: 2.2.0   ◄── bump born here, never flows back
                      \
main ─────────────────►  2.2.0   tag v2.2.0

Why it matters

• A branch cut from a milestone-merge branch silently carries the bump into an unrelated PR. This is not hypothetical — it happened on fix: bind loopback by address and pin the sandbox port for containers #2009, where a container bugfix arrived with package.json 2.0.0 → 2.2.0 in its diff and would have bumped the develop branch's version as a side effect of a bug fix. It was caught in review and rebased out.
• Anything reading the version during development reports 2.0.0 — readInspectorVersion(), --version, and the web GET /api/config payload. Bug reports from a dev build name a version that is two releases old.
• It compounds. Every release widens the gap, and every new branch cut from the wrong base inherits a larger, more confusing diff.

Fix — bump on v2/main, before the milestone merge

Move the npm version step so the bump happens on v2/main, and then flows into main with the rest of the milestone's work. No back-merge, no sync step, and no window in which the two disagree:

v2/main ──► chore: 2.3.0 ──────►  2.3.0  ✓ in sync
              \
milestone-br   ├─ merge v2/main (carries the bump)
                    \
main ───────────────►  2.3.0   tag 2.3.0

Procedure becomes:

1. On a branch off v2/main: npm version <major|minor|patch> --no-git-tag-version, PR to v2/main.
2. Milestone-merge branch as today, which now carries the bump into main.
3. Tag the resulting main commit (git tag 2.3.0 <sha> && git push origin 2.3.0) and draft the Release from that tag.

The release workflow needs no change: its "Assert release tag matches package version" step runs at the release commit on main, which still carries the bump.

Why not a back-merge (main → v2/main, the conventional git-flow answer): main carries 230 commits v2/main does not — the entire pre-v2 v1 history retained through ec5d8e13 chore: replace main's tree with v2. Merging would graft all of it into the develop branch's log permanently, to deliver a two-file change. A post-release sync commit avoids the graft but is still a forgettable extra step with a drift window; bumping first has neither.

Scope

• One-time catch-up: set v2/main to 2.2.0 to match the current release.
• Rewrite the Cutting a release section of the root README.md.
• Update the branch-flow description in AGENTS.md so the two agree.

Nothing in the repo asserts a specific version value (no test reads it), so the catch-up is a safe two-file change.

[cliffhall]

Triage: Priority Medium (total 6)

• Severity 3 — a real defect risk, already realized once: fix: bind loopback by address and pin the sandbox port for containers #2009 arrived carrying an unrelated version bump in its diff
• Urgency 3 — wanted this milestone; the next milestone merge repeats the drift if this lands after it
• Bonuses: none claimed (chore, not bug; the milestone is by construction of the create flow, not an independent approval)

Board: #28, Status In Progress, milestone v2.3.0.

[cliffhall]

Fixed by #2011, merged to v2/main (ebeaa14).

v2/main now reads 2.2.0, matching main and npm latest — the drift that had persisted since the v2.0.0 release is closed.

Going forward the version bump is made on v2/main, before the milestone merge, so it flows into main with the rest of the milestone's work. The release tag (bare x.y.z, no v prefix) is applied to origin/main afterwards. Full procedure in the root README's Cutting a release, with the branch-flow summary in AGENTS.md.

Three things the review surfaced that are worth knowing before the first release through the new flow:

• npm version must carry --no-git-tag-version. Otherwise it tags a v2/main commit, and the release must be cut from main.
• Tag origin/main explicitly — git tag 2.3.0 origin/main, not git checkout main && git pull then tagging HEAD. A divergent local main can produce a local commit, and git push origin <tag> pushes only the tag, leaving a release pointing at something never published. The publish job would not catch it.
• The branches legitimately differ while a release is in flight (v2/main on the version being built, main on the released one). Ahead is expected; behind means something went wrong.

v2.3.0 will be the first release through this procedure — worth walking the three steps deliberately that once.