@adia-ai/adia-ui-forge 0.8.58 → 0.8.60

package/skills/package-release/scripts/release-pack.mjs

@@ -71,6 +71,11 @@ import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
 import { resolvePackageChangelog, PACKAGE_ROSTER } from './package-paths.mjs';
 import { GATE_ROSTER } from './gate-roster.mjs';
+// gh#3361: Step 5's releaseFiles derives its PINNED_REFS-covered entries
+// from bump.mjs's own tables (below, pinnedRefFiles()) instead of
+// hand-duplicating them — bump.mjs guards its own main()/selftest() behind
+// an entry-point check specifically so this import is side-effect-free.
+import { PINNED_REFS, REPO_PINNED_REFS } from './bump.mjs';
 
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
 const REPO = process.cwd();
@@ -88,6 +93,26 @@ const DEFAULT_NPM_SCOPE = '@adia-ai';
 const LOCKSTEP_ROSTER = PACKAGE_ROSTER.filter((p) => p.lockstep !== false);
 const PACKAGES = LOCKSTEP_ROSTER.map((p) => p.name);
 
+// Reject a --substantive-packages/--stub-packages name whose roster entry is
+// unknown or lockstep:false, BEFORE Step 1 runs (gh#2894). The 0.8.58 cut
+// passed `adia-plugins` (lockstep:false, gh#1133) in --substantive-packages;
+// promote-unreleased.mjs happily rewrote its CHANGELOG's [Unreleased] header
+// to a version that package doesn't ship, and the cut only caught it at Step
+// 5.6's unstaged-tracked-files guard — AFTER the 34-gate pre-flight had
+// already run. Matches PACKAGE_ROSTER by name form (`adia-plugins`) or dir
+// form minus the `packages/` prefix (`plugins/adia-plugins`).
+function assertLockstepPackages(names) {
+  for (const pkg of names) {
+    const entry = PACKAGE_ROSTER.find(
+      (p) => p.name === pkg || p.dir.replace(/^packages\//, '') === pkg,
+    );
+    if (!entry || entry.lockstep === false) {
+      console.error(`error: --substantive-packages/--stub-packages package "${pkg}" is not lockstep:true in scripts/package-paths.mjs PACKAGE_ROSTER (unknown or class-B) — rejected before Step 1.`);
+      process.exit(2);
+    }
+  }
+}
+
 function parseArgs(argv) {
   const args = {
     version: null, date: null, previous: null, mode: null,
@@ -98,6 +123,7 @@ function parseArgs(argv) {
     host: process.env.ADIA_DEPLOY_HOST || DEFAULT_DEPLOY_HOST,
     scope: process.env.ADIA_NPM_SCOPE || DEFAULT_NPM_SCOPE,
     dry: false, yes: false, push: false, publish: false, skipGates: false, skipSite: false,
+    fromStep10: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const k = argv[i];
@@ -128,6 +154,15 @@ function parseArgs(argv) {
     else if (k === '--go') { args.yes = true; args.push = true; args.publish = true; }
     else if (k === '--skip-gates') args.skipGates = true;
     else if (k === '--skip-site') args.skipSite = true;
+    // gh#3342: resume a handoff that already tagged/pushed/published — a
+    // straight re-run of `--mode handoff` re-gates (Step 3 never runs in
+    // handoff mode, but Step 6 would re-tag at HEAD, which may no longer be
+    // the tagged commit if anything merged since) and Step 9 would
+    // re-dispatch publishes that already succeeded (idempotent, but a
+    // needless wait). `--from-step10` skips straight to Step 10 (GH
+    // releases + site deploy) — the exact "resume from Step 10 only" shape
+    // the v0.8.59 cut needed by hand (a one-off script, never checked in).
+    else if (k === '--from-step10') args.fromStep10 = true;
     else if (k === '-h' || k === '--help') { help(); process.exit(0); }
   }
   if (!args.version || !args.date || !args.previous || !args.mode) {
@@ -148,6 +183,12 @@ function parseArgs(argv) {
     console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
+  // Roster validation (gh#2894), before any mode-specific check below —
+  // applies to BOTH cut and from-scratch (the script's own --help text shows
+  // both flags on a `cut` invocation).
+  if (args.substantivePackages || args.stubPackages) {
+    assertLockstepPackages([...(args.substantivePackages ?? []), ...(args.stubPackages ?? [])]);
+  }
   // Handoff needs the GH-notes body at Step 10 — validate at PARSE time, not
   // there: on the v0.8.10 cut the missing flag surfaced only after tags and
   // npm publish were already irreversible (Step 10 is the LAST step). An arg
@@ -209,6 +250,10 @@ function parseArgs(argv) {
       console.error(`error: GH notes file not found or not a regular file: ${args.ghNotesFile}`);
       process.exit(2);
     }
+  } else if (args.fromStep10) {
+    console.error('error: --from-step10 only applies to --mode handoff (it resumes handoff\'s own');
+    console.error('       tag→publish→deploy sequence at its last step) — got --mode ' + args.mode);
+    process.exit(2);
   }
   return args;
 }
@@ -233,8 +278,13 @@ Flags: --go   (single-authorization: the operator's cut-start go covers the
        --push  (auto-confirm checkpoint 2 — push tags)
        --publish  (auto-confirm checkpoint 3 — dispatch publishes)
        --skip-site  (skip EXE deploy)
+       --from-step10  (--mode handoff only: resume at Step 10 — GH releases +
+               site deploy — skipping the pre-flight gates and re-tagging;
+               use once Steps 1-9 are independently confirmed done. See
+               recovery-paths.md §Scenario 9.)
 Instance: --host <deploy-host>  (default ${DEFAULT_DEPLOY_HOST}; or $ADIA_DEPLOY_HOST)
-          --scope <@org>        (npm scope; default ${DEFAULT_NPM_SCOPE}; or $ADIA_NPM_SCOPE)`);
+          --scope <@org>        (npm scope; default ${DEFAULT_NPM_SCOPE}; or $ADIA_NPM_SCOPE)
+          $REGISTRY_POLL_MINUTES  (Step 9 registry-poll window; default 30)`);
 }
 
 const rl = createInterface({ input: stdin, output: stdout });
@@ -714,6 +764,27 @@ async function step3PreFlight(args) {
     return;
   }
   console.log(`\n=== Step 3 — Pre-flight gates (${GATE_ROSTER.length}-gate roster — gate-roster.mjs) ===`);
+
+  // gh#3342: gate 4 (test:unit:serial) runs package-root `*.test.js` files
+  // for llm/agent/persona against their BUILT tsc output — agent.test.js's
+  // own docstring: "run against the BUILT output ... npm run build
+  // -w @adia-ai/agent first"; persona.test.js imports './index.js' directly;
+  // llm/core carries a dedicated dist-check.test.js that asserts the emitted
+  // artifacts exist and explicitly does NOT build them itself ("callers
+  // should run npm run build first"). All three packages' emitted .js/.d.ts
+  // are gitignored (packages/llm/agent/.gitignore: "Generated by npm run
+  // build ... not tracked in git"), so a fresh cut clone has none of them.
+  // cut-procedure.md §3.0's harvest preamble names `npm run build
+  // -w @adia-ai/llm` but that whole block is CONDITIONAL on source content
+  // having changed in the window, and never named agent/persona at all — a
+  // cut with no §3.0 trigger skipped the build outright and gate 4 failed
+  // on missing dist (the v0.8.59 cut). Unlike §3.0's regen outputs, these
+  // are plain build artifacts, not content-conditional — build them
+  // unconditionally, every cut, before gate 4 ever runs. Runs before the
+  // `--dry` early-return below so a dry preview shows it too.
+  console.log('\n-- Precondition: tsc build (llm, agent, persona — gate 4 needs their built output) --');
+  sh('npm run build -w @adia-ai/llm -w @adia-ai/agent -w @adia-ai/persona', args);
+
   if (args.dry) {
     step3PreFlightDry(args);
     return;
@@ -947,6 +1018,31 @@ function step4PromoteAndBump(args) {
     console.log('  ✓ Hermes/Pi plugin manifests fresh after regeneration');
   }
 
+  // Step 4d.8 — rebuild the dist CSS+JS bundles (gh#3342): bump.mjs's
+  // web-components PINNED_REFS entry moves icons-cdn.js's hand-typed
+  // PACKAGE_VERSION literal every cut (gh#3240/invariant 9), and that
+  // literal is embedded verbatim in three committed dist bundles
+  // (web-components.min.js, everything.min.js, chat-shell.min.js) —
+  // same "derived artifact embeds the lockstep version" class as 4d.5-4d.7
+  // above. Gate 9 (check:js-bundles-fresh) runs pre-bump in Step 3 and only
+  // proves freshness against the PREVIOUS version; relying on the
+  // derived-resync bot to rebuild post-merge left gate 9 red in the
+  // handoff pre-flight (AGENTS.md: committed dist/ bundles are PR-blocking,
+  // Class C — never a derived-resync-only artifact). Rebuild here, under
+  // the same npm-ci layout Step 1 already asserted for gate 9, and verify:
+  console.log('\n  Step 4d.8 — rebuild dist CSS+JS bundles (icons-cdn.js pin embeds the lockstep bump):');
+  sh('npm run build:bundles', args);
+  if (args.dry) {
+    console.log('  [dry] npm run check:css-bundles-fresh && npm run check:js-bundles-fresh (post-rebuild proof)');
+  } else if (!shOk('npm run check:css-bundles-fresh') || !shOk('npm run check:js-bundles-fresh')) {
+    console.error('\nERROR: dist bundles still stale after rebuild — build:bundles did not produce');
+    console.error('       output matching check:css-bundles-fresh/check:js-bundles-fresh\'s expectations.');
+    console.error('       Run both by hand to diagnose before re-running the cut.');
+    process.exit(1);
+  } else {
+    console.log('  ✓ dist CSS+JS bundles fresh after rebuild');
+  }
+
   // Step 4e — generate docs/ops/releases/vX.Y.Z.md (gh#399: neither this step nor
   // its staging into the release commit existed before — check-cut-hygiene's
   // "notes present" claim (Step 4g, below) went unverified until
@@ -976,6 +1072,27 @@ function step4PromoteAndBump(args) {
   }
 }
 
+// gh#3361: derive Step 5's PINNED_REFS-covered allowlist entries directly
+// from bump.mjs's own tables, instead of hand-listing the same paths a
+// second time — the drift class this closes structurally (gh#1198, gh#1899,
+// gh#1954, gh#2473, gh#3342): every one of those was bump.mjs gaining a new
+// pinned file that release-pack.mjs's Step 5 didn't independently know
+// about. A package-keyed entry becomes `<pkgDir>/<file>`; a repo-level entry
+// (REPO_PINNED_REFS, e.g. the root README's "Current version" claim) is
+// already repo-root-relative. Pure — the selftest below asserts the
+// derivation against a fixture table, and separately that it agrees with
+// the REAL imported PINNED_REFS/REPO_PINNED_REFS for every entry currently
+// known (so an entry added to bump.mjs without a corresponding
+// release-pack.mjs edit still shows up here for free).
+function pinnedRefFiles(pinnedRefs, repoPinnedRefs) {
+  const files = [];
+  for (const [pkgDir, cfgs] of Object.entries(pinnedRefs)) {
+    for (const cfg of cfgs) files.push(`${pkgDir}/${cfg.file}`);
+  }
+  for (const cfg of repoPinnedRefs) files.push(cfg.file);
+  return files;
+}
+
 // Pure so the selftest can lock the parse without a real git tree (gh#2473,
 // same "pure so selftest can lock the transform" shape as bump.mjs's
 // bumpPinnedRef). Takes `git status --porcelain` output, returns the tracked
@@ -1043,10 +1160,10 @@ function step5Commit(args) {
   sh('git reset HEAD >/dev/null 2>&1 || true', args);
   const releaseFiles = [
     'package-lock.json',
-    // Root README's "Current version" claim — bump.mjs moves it per-cut
-    // (REPO_PINNED_REFS); gate 18 (check-cut-hygiene doc-currency) exact-matches
-    // it against the cut version, so it must ride the release commit.
-    'README.md',
+    // Root README's "Current version" claim (gate 18, check-cut-hygiene
+    // doc-currency, exact-matches it against the cut version) comes from
+    // pinnedRefFiles(REPO_PINNED_REFS) below — bump.mjs's own REPO_PINNED_REFS
+    // table names this exact file (gh#3361).
     // Root CHANGELOG — the gh#453 promotion machinery renames its
     // [Unreleased] heading at Step 4, but this roster predated it, so the
     // v0.8.20 cut promoted the heading and then shipped WITHOUT it (the
@@ -1071,6 +1188,17 @@ function step5Commit(args) {
     'packages/genui/adia-catalog/adia.agent.json',
     'packages/genui/adia-catalog/adia.shells.json',
     'packages/genui/adia-catalog/catalog-data.js',
+    // gh#3342/gh#3361: packages/web-components/core/icons-cdn.js (bump.mjs's
+    // PACKAGE_VERSION pin, fifth instance of this drift class — gh#1198,
+    // gh#1899, gh#1954, gh#2473) comes from pinnedRefFiles(PINNED_REFS)
+    // below, not a hand-typed entry — bump.mjs's own PINNED_REFS table names
+    // it, so it can't drift out of this list again.
+    // gh#3342: Step 4d.8 rebuilds the dist CSS+JS bundles post-bump (the
+    // icons-cdn.js PACKAGE_VERSION pin above is embedded in three of them) —
+    // directory pathspecs, `git add` stages whatever the rebuild actually
+    // changed, same shape as the chunk-corpus/skills-glob entries below.
+    'packages/web-components/dist',
+    'packages/web-modules/dist',
     // gh#1361: Step 4d.5b regenerates the catalog tier index post-bump (it
     // derives from the catalog derive-genui-catalog.mjs just refreshed) and,
     // when that regen goes stale against the chunk harvester's recorded
@@ -1121,19 +1249,25 @@ function step5Commit(args) {
         // Codex `agents/openai.yaml` glob above is.
         files.push(`${dir}/plugin.yaml`, `${dir}/__init__.py`, `${dir}/prompts/*.md`);
       }
-      // gh#2473: bump.mjs's PINNED_REFS also rewrites the factory README's
-      // OWN prose echo of the generation-MCP pin (`server pinned:
-      // @adia-ai/mcp@X` — see bump.mjs's A2UI_MCP_PIN comment,
-      // check:plugin-count-claims' "factory README generation-MCP pin"
-      // equality check) — same invariant-8 scope as .mcp.json, but this
-      // list only ever staged .mcp.json + hermes-mcp.yaml, so the README
-      // edit rode along unstaged/uncommitted every cut until Step 5.6
-      // (below) started catching it.
-      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`, `${dir}/README.md`);
+      // gh#1954: Step 4d.7 also regenerates the factory's Hermes/Pi
+      // hermes-mcp.yaml fragment post-bump — not PINNED_REFS-covered (it's
+      // a manifest-generator output, not a version-pin literal), so it
+      // stays hand-listed here. factory's `.mcp.json` + `README.md`
+      // generation-MCP pins (gh#1198, gh#2473 — same invariant-8 scope) come
+      // from pinnedRefFiles(PINNED_REFS) below instead (gh#3361).
+      if (name === 'adia-ui-factory') files.push(`${dir}/hermes-mcp.yaml`);
       return files;
     }),
+    // gh#3361: every PINNED_REFS/REPO_PINNED_REFS-covered file, derived
+    // straight from bump.mjs's own tables — see pinnedRefFiles()'s header
+    // comment for what this closes. Deduped below against entries this list
+    // already carries for OTHER reasons (e.g. every roster package's own
+    // package.json is already staged above; web-modules' peer-pin entry
+    // targets that same package.json).
+    ...pinnedRefFiles(PINNED_REFS, REPO_PINNED_REFS),
   ];
-  sh(`git add ${releaseFiles.join(' ')}`, args);
+  const dedupedReleaseFiles = [...new Set(releaseFiles)];
+  sh(`git add ${dedupedReleaseFiles.join(' ')}`, args);
   sh('git diff --cached --stat | tail -3', args);
 
   // Step 5.6 — unstaged-tracked-files guard (gh#2473). Numbered 5.6, not
@@ -1291,6 +1425,77 @@ function registrySnapshot(args) {
   return `Registry state BEFORE publish (target = ${args.version}):\n${lines.join('\n')}`;
 }
 
+async function sleepMs(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+// Registry truth for the Step 9 poll — which packages (plus, as the sentinel
+// entry 'dist-tags.latest', the tag itself) have NOT yet converged on the
+// target version. [] means fully converged.
+function registryStalePackages(args, scope, version) {
+  const stale = [];
+  for (const pkg of PACKAGES) {
+    let v;
+    try { v = execSync(`npm view "${scope}/${pkg}" version`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+    catch { v = null; }
+    if (v !== version) stale.push(pkg);
+  }
+  let latest;
+  try { latest = execSync(`npm view ${scope}/web-components dist-tags.latest`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+  catch { latest = null; }
+  if (latest !== version) stale.push('dist-tags.latest');
+  return stale;
+}
+
+// gh#3342: npm now stages a large publish ASYNCHRONOUSLY — the tarball can
+// take up to ~25 minutes to actually become visible on `npm view`, well past
+// this poll's former 10-minute bound (the v0.8.59 cut hit exactly this). A
+// re-dispatch of the publish workflow while a package is in that state fails
+// its own `npm publish` step with npm error E409 ("Cannot publish over
+// previously staged version") — that error IS the staged-not-lost signal
+// (npm rejected the duplicate BECAUSE the real publish already landed
+// server-side), never a real failure. Check the package's latest
+// publish-<pkg>.yml run: a FAILED conclusion whose log matches the E409
+// signature confirms staged-not-lost; anything else (no failed run, or a
+// failure that isn't E409) is a genuine miss. Never throws — a gh query
+// failure just means "not confirmed E409", the conservative default so a
+// genuine miss is never masked.
+function publishRunFailedWithE409(pkg) {
+  try {
+    const runId = execSync(
+      `gh run list --workflow=publish-${pkg}.yml --limit 1 --json databaseId,conclusion -q '.[0] | select(.conclusion=="failure") | .databaseId'`,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+    ).trim();
+    if (!runId) return false;
+    const log = execSync(`gh run view ${runId} --log-failed`, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+    return /E409|previously staged/i.test(log);
+  } catch {
+    return false;
+  }
+}
+
+// Poll the registry every 15s up to `minutes`, logging progress the same way
+// the original bash loop did. Returns the still-stale list (empty = fully
+// converged) — never throws; the caller decides what a non-empty result means.
+async function pollRegistry(args, scope, version, minutes, label) {
+  if (args.dry) {
+    console.log(`  [dry] ${label} poll skipped (up to ${minutes}min, every 15s)`);
+    return [];
+  }
+  const checks = Math.max(1, Math.round((minutes * 60) / 15));
+  let stale = PACKAGES.length ? [...PACKAGES, 'dist-tags.latest'] : [];
+  for (let i = 1; i <= checks; i++) {
+    stale = registryStalePackages(args, scope, version);
+    if (stale.length === 0) {
+      console.log(`  ✓ ${label} confirms all ${PACKAGES.length} + latest, after ${i} check(s)`);
+      return [];
+    }
+    if (i < checks) await sleepMs(15000);
+  }
+  console.log(`  ${label} did not converge after ${minutes}min — still stale: ${stale.join(', ')}`);
+  return stale;
+}
+
 async function step9Publish(args) {
   console.log('\n=== Step 9 — Verify-triggered + re-dispatch misses ===');
   const evidence = registrySnapshot(args);
@@ -1308,39 +1513,105 @@ async function step9Publish(args) {
   // Poll the REGISTRY itself instead — the skill's own doctrine (SKILL.md:
   // "the registry is the verify target, never a workflow's green check")
   // applies here as much as it does to the final check.
-  console.log(`\n  Waiting for the registry to confirm all ${PACKAGES.length} packages at ${args.version} (polling every 15s, up to 10min)...`);
-  sh(
-    `for i in $(seq 1 40); do ` +
-    `fail=0; ` +
-    `for pkg in ${PACKAGES.join(' ')}; do ` +
-    `v="$(npm view "${args.scope}/$pkg" version 2>/dev/null || true)"; ` +
-    `[ "$v" = "${args.version}" ] || fail=1; ` +
-    `done; ` +
-    `latest="$(npm view ${args.scope}/web-components dist-tags.latest 2>/dev/null || true)"; ` +
-    `[ "$latest" = "${args.version}" ] || fail=1; ` +
-    `[ "$fail" = 0 ] && { echo "  ✓ registry confirms all ${PACKAGES.length} + latest, after $i check(s)"; exit 0; }; ` +
-    `sleep 15; ` +
-    `done; ` +
-    `echo "  registry did not converge after 10min — the fail-closed check below will report exactly which package(s) are still stale"`,
-    args,
-  );
+  //
+  // gh#3342: the poll window moved from a flat 10 minutes to
+  // REGISTRY_POLL_MINUTES (default 30) — npm stages a large publish
+  // ASYNCHRONOUSLY and the tarball can take up to ~25 minutes to become
+  // visible on `npm view`, past the old bound (the v0.8.59 cut hit this and
+  // exited 1 with every publish run actually green).
+  const pollMinutes = Number(process.env.REGISTRY_POLL_MINUTES) || 30;
+  console.log(`\n  Waiting for the registry to confirm all ${PACKAGES.length} packages at ${args.version} (polling every 15s, up to ${pollMinutes}min)...`);
+  let stale = await pollRegistry(args, args.scope, args.version, pollMinutes, 'registry');
+
+  // gh#3342: a still-stale package here may be genuinely missing, OR it may
+  // be staged-but-not-yet-visible — distinguish via its latest publish run.
+  // A run that failed specifically on npm's E409 ("Cannot publish over
+  // previously staged version") proves the package IS staged: npm rejected
+  // the (redundant) publish attempt BECAUSE the real one already landed
+  // server-side. That is the staged-not-lost signal this ticket exists to
+  // handle — never a hard failure, and never itself grounds to re-dispatch
+  // again (a THIRD publish attempt would only 409 again). Give
+  // E409-confirmed packages one more extended, isolated poll; a package
+  // with no E409 signal is a genuine miss and skips straight to the
+  // fail-closed report below.
+  if (stale.length > 0 && !args.dry) {
+    const staleePkgs = stale.filter((p) => p !== 'dist-tags.latest');
+    const e409 = staleePkgs.filter((pkg) => publishRunFailedWithE409(pkg));
+    if (e409.length > 0) {
+      console.log(`\n  ${e409.length} stale package(s) confirmed E409 (staged, not lost) — extending the poll another ${pollMinutes}min: ${e409.join(', ')}`);
+      console.log('  (a genuinely missing package would show no failed run, or a failure that is not E409 — those are NOT extended)');
+      // The fail-closed block below re-queries the registry fresh regardless
+      // of this poll's own result — this extended wait exists to let a
+      // genuinely staged package converge before that final read, not to
+      // compute the verdict itself.
+      await pollRegistry(args, args.scope, args.version, pollMinutes, 'extended registry poll');
+    }
+  }
+
   // Fail-closed: the registry is the verify target (SKILL.md) — a missing or
   // stale package aborts the cut here, before GH releases + site deploy. This
-  // is now a final confirmation of the poll above, not the first real read.
+  // is now a final confirmation of the poll(s) above, not the first real read.
   console.log(`\n  Post-publish registry verification, all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
-  sh(
-    `fail=0; ` +
-    `for pkg in ${PACKAGES.join(' ')}; do ` +
-    `v="$(npm view "${args.scope}/$pkg" version 2>/dev/null || true)"; ` +
-    `echo "  $pkg: \${v:-MISSING}"; ` +
-    `[ "$v" = "${args.version}" ] || fail=1; ` +
-    `done; ` +
-    `latest="$(npm view ${args.scope}/web-components dist-tags.latest 2>/dev/null || true)"; ` +
-    `echo "  latest: \${latest:-MISSING}"; ` +
-    `[ "$latest" = "${args.version}" ] || fail=1; ` +
-    `[ "$fail" = 0 ] || { echo "ERROR: registry does not confirm ${args.version} across all ${PACKAGES.length} packages — fix before GH releases/deploy"; exit 1; }`,
-    args,
-  );
+  if (args.dry) {
+    console.log('  [dry] registry re-verify skipped');
+    return;
+  }
+  const final = registryStalePackages(args, args.scope, args.version);
+  for (const pkg of PACKAGES) {
+    console.log(`  ${pkg}: ${final.includes(pkg) ? 'MISSING' : args.version}`);
+  }
+  console.log(`  latest: ${final.includes('dist-tags.latest') ? 'MISSING' : args.version}`);
+  if (final.length > 0) {
+    console.error(`ERROR: registry does not confirm ${args.version} across all ${PACKAGES.length} packages — fix before GH releases/deploy`);
+    console.error(`  still stale: ${final.join(', ')}`);
+    process.exit(1);
+  }
+}
+
+// Precondition for `--from-step10` (critic finding on PR #3364): jumping
+// straight to Step 10 without checking the release tags exist is a silent
+// trap — `gh release create <tag>` on a tag that doesn't exist yet mints a
+// NEW lightweight tag at whatever HEAD happens to be, not the real tagged
+// release commit. Refuse the resume outright unless every tag Step 6 would
+// have created (umbrella + all per-package) already exists on origin and
+// points at HEAD.
+function assertReleaseTagsAtHead(args) {
+  console.log('\n  Precondition — verifying release tags already exist and point at HEAD before resuming at Step 10:');
+  const headSha = shQuiet('git rev-parse HEAD', args).trim();
+  const tags = [`v${args.version}`, ...PACKAGES.map((p) => `${p}-v${args.version}`)];
+  if (args.dry) {
+    console.log(`  [dry] git fetch origin ${tags.map((t) => `tag ${t}`).join(' ')}`);
+    console.log(`  [dry] verify each of ${tags.length} tags resolves to HEAD (${headSha || '<dry HEAD>'})`);
+    return;
+  }
+  sh(`git fetch origin ${tags.map((t) => `tag ${t}`).join(' ')}`, args);
+  const missing = [];
+  const mismatched = [];
+  for (const tag of tags) {
+    let tagSha;
+    try {
+      tagSha = execSync(`git rev-parse "${tag}^{commit}"`, { cwd: REPO, encoding: 'utf8' }).trim();
+    } catch {
+      missing.push(tag);
+      continue;
+    }
+    if (tagSha !== headSha) mismatched.push(`${tag} -> ${tagSha}`);
+  }
+  if (missing.length > 0 || mismatched.length > 0) {
+    console.error('\nERROR: --from-step10 refuses to resume — the release tags this handoff needs are not all present at HEAD.');
+    if (missing.length > 0) {
+      console.error(`  Missing entirely (Step 6 creates these, Step 8 pushes them to origin): ${missing.join(', ')}`);
+    }
+    if (mismatched.length > 0) {
+      console.error(`  Point somewhere other than HEAD (${headSha}): ${mismatched.join(', ')}`);
+    }
+    console.error('  Resuming Step 10 here would let `gh release create` mint NEW lightweight tags at the');
+    console.error('  current HEAD instead of using the real tagged release commit — silently wrong.');
+    console.error('  Fix: confirm the original handoff run actually reached Step 8 (tags pushed to origin)');
+    console.error('  and that HEAD has not moved since, or re-run the full handoff instead of --from-step10.');
+    process.exit(1);
+  }
+  console.log(`  ✓ all ${tags.length} release tags exist on origin and point at HEAD (${headSha})`);
 }
 
 // ── Step 10 — GH releases + site deploy ──────────────────────────
@@ -1493,6 +1764,22 @@ async function main() {
       console.error(`     node ${repoCopy} <same args>\n`);
     }
   }
+  // gh#3342: --from-step10 resumes a handoff that already tagged, pushed,
+  // and published — skip straight to Step 10 (GH releases + site deploy)
+  // rather than a plain re-run, which would re-run the full pre-flight gate
+  // roster (Step 3, ~15min) AND re-tag at HEAD (Step 6, wrong if anything
+  // merged since the original tag). Every step this skips is either
+  // idempotent-but-wasteful (3, 9) or actively wrong to repeat (6, if HEAD
+  // moved) — a real operational need the v0.8.59 cut hit and worked around
+  // with a one-off, never-checked-in script.
+  if (args.mode === 'handoff' && args.fromStep10) {
+    console.log('\n[resume --from-step10] skipping Steps 1/3/4/5/6/7/8/9 (already tagged/pushed/published) — jumping straight to Step 10.');
+    assertReleaseTagsAtHead(args);
+    await step10GhAndSite(args);
+    rl.close();
+    console.log('\n✓ release-pack complete (resumed at Step 10). Verify against the npm registry + GH releases, then author the release notes.');
+    return;
+  }
   // gh#765: an aborted Step-4 run leaves bumped versions + promoted
   // CHANGELOGs; detect BEFORE pre-flight so gate 24 validates at the right
   // version and Step 4 skips the already-done promote/stub/bump.
@@ -1626,6 +1913,50 @@ async function selftest() {
       }
     }
 
+    // gh#3361 — pinnedRefFiles() must derive `<pkgDir>/<file>` for a
+    // package-keyed entry and the bare `file` for a repo-level entry, from a
+    // FIXTURE table (independent of bump.mjs's real, evolving content).
+    {
+      const fixturePinned = {
+        'packages/plugins/fake-plugin': [{ file: '.mcp.json' }, { file: 'README.md' }],
+        'packages/fake-pkg': [{ file: 'core/pinned.js' }],
+      };
+      const fixtureRepoPinned = [{ file: 'README.md' }];
+      const got = pinnedRefFiles(fixturePinned, fixtureRepoPinned);
+      const want = [
+        'packages/plugins/fake-plugin/.mcp.json',
+        'packages/plugins/fake-plugin/README.md',
+        'packages/fake-pkg/core/pinned.js',
+        'README.md',
+      ];
+      if (JSON.stringify(got) !== JSON.stringify(want)) {
+        console.error(`selftest FAIL: pinnedRefFiles() expected ${JSON.stringify(want)}, got ${JSON.stringify(got)}`);
+        process.exit(1);
+      }
+    }
+    // gh#3361 — the structural guarantee this ticket exists for: every path
+    // bump.mjs's REAL, imported PINNED_REFS/REPO_PINNED_REFS tables name is
+    // present in Step 5's assembled releaseFiles (the `--mode cut --dry`
+    // subprocess run below), proven by literally re-deriving the expected
+    // set from the SAME imported tables the subprocess itself reads — a
+    // future PINNED_REFS entry with no matching releaseFiles line (the
+    // gh#1198/1899/1954/2473/3342 drift shape) fails HERE, not three cuts
+    // later at Step 5.6.
+    {
+      const expectedPinned = pinnedRefFiles(PINNED_REFS, REPO_PINNED_REFS);
+      if (expectedPinned.length === 0) {
+        console.error('selftest FAIL: bump.mjs\'s real PINNED_REFS/REPO_PINNED_REFS produced zero derived paths — the import is broken');
+        process.exit(1);
+      }
+      // The fixture set itself must never silently reduce to nothing new —
+      // proves gh#3342's icons-cdn.js entry specifically survived the
+      // gh#3361 refactor (it's the exact file that motivated this ticket).
+      if (!expectedPinned.includes('packages/web-components/core/icons-cdn.js')) {
+        console.error(`selftest FAIL: pinnedRefFiles(PINNED_REFS, REPO_PINNED_REFS) is missing packages/web-components/core/icons-cdn.js — got ${JSON.stringify(expectedPinned)}`);
+        process.exit(1);
+      }
+    }
+
     // gh#2473 — Step 5.6's guard: unstagedTrackedLeftovers() must find a
     // plain modified/deleted tracked file, unquote a C-quoted path
     // (spaces), and report the NEW side of a rename/copy — all from a
@@ -1689,6 +2020,11 @@ async function selftest() {
       `${GATE_ROSTER.length}-gate roster`,
       `✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`,
       'STOPPING per invariant 3',
+      // gh#3342 — gate 4 needs llm/agent/persona's BUILT (tsc) output, not
+      // just conditionally regenerated content; the precondition must run
+      // even in a --dry preview, before the gate roster itself.
+      'Precondition: tsc build (llm, agent, persona',
+      '[dry] npm run build -w @adia-ai/llm -w @adia-ai/agent -w @adia-ai/persona',
       // gh#358 — the release branch must actually be created, not just documented.
       'git checkout -b release/v9.9.9',
       // gh#1197 — Step 5's staging pathspec must carry gate 28's committed
@@ -1726,6 +2062,19 @@ async function selftest() {
       // README target), or it rides unstaged/uncommitted past the release
       // commit the same way .mcp.json itself did before gh#1198.
       'packages/plugins/adia-ui-factory/README.md',
+      // gh#3342 — fifth instance of the same allowlist-drift class
+      // (gh#1198, gh#1899, gh#1954, gh#2473): bump.mjs's web-components
+      // PINNED_REFS entry moves icons-cdn.js's PACKAGE_VERSION literal
+      // every cut; the v0.8.59 cut hit Step 5.6's guard on this exact file.
+      'packages/web-components/core/icons-cdn.js',
+      // gh#3342 — Step 4d.8 rebuilds the dist bundles post-bump (the
+      // icons-cdn.js pin above is embedded in three of them) and Step 5
+      // must stage the result, or gate 9 (check:js-bundles-fresh) fails in
+      // the handoff pre-flight the way the v0.8.59 cut's did.
+      'Step 4d.8 — rebuild dist CSS+JS bundles',
+      '[dry] npm run build:bundles',
+      'packages/web-components/dist',
+      'packages/web-modules/dist',
       // gh#2473 — Step 5.6's unstaged-tracked-files guard must actually run
       // (as a no-op) on a clean --dry plan. Its real leftover-detection
       // logic is unit-tested directly above via unstagedTrackedLeftovers();
@@ -1753,6 +2102,37 @@ async function selftest() {
       process.exit(1);
     }
 
+    // gh#2894 — a --substantive-packages/--stub-packages name whose roster
+    // entry is lockstep:false (or unknown) must die at PARSE time, naming
+    // the roster file, BEFORE Step 1 runs. The 0.8.58 cut passed
+    // `adia-plugins` (lockstep:false) in --substantive-packages and only
+    // caught it at Step 5.6, after the 34-gate pre-flight had already run.
+    const rosterRejectShapes = [
+      { flags: '--substantive-packages adia-plugins', name: 'adia-plugins' },
+      { flags: '--stub-packages totally-unknown-package', name: 'totally-unknown-package' },
+    ];
+    for (const { flags, name } of rosterRejectShapes) {
+      let failed = false;
+      let out = '';
+      try {
+        execSync(
+          `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ${flags} --dry`,
+          { cwd: REPO, encoding: 'utf8' },
+        );
+      } catch (e) {
+        failed = true;
+        out = (e.stdout || '') + (e.stderr || '');
+      }
+      if (!failed || !out.includes(name) || !out.includes('package-paths.mjs PACKAGE_ROSTER')) {
+        console.error(`selftest FAIL: --substantive-packages/--stub-packages "${name}" must hard-reject naming scripts/package-paths.mjs PACKAGE_ROSTER`);
+        process.exit(1);
+      }
+      if (out.includes('=== Step 1') || out.includes('gate roster')) {
+        console.error(`selftest FAIL: the roster guard for "${name}" must fire BEFORE Step 1, not after`);
+        process.exit(1);
+      }
+    }
+
     // gh#765 — from-scratch with substantive-but-no-stub packages must die at
     // PARSE time, naming the ride-alongs, BEFORE any pre-flight gate runs
     // (v0.8.29 burned three ~15-min pre-flight re-runs discovering it at
@@ -1851,6 +2231,62 @@ async function selftest() {
       process.exit(1);
     }
 
+    // gh#3364 critic finding — `--from-step10` must (a) only apply to
+    // --mode handoff, at parse time, and (b) refuse to resume without first
+    // verifying the release tags already exist and point at HEAD (otherwise
+    // `gh release create` on a tag that was never made mints a NEW
+    // lightweight tag at whatever HEAD happens to be — silently wrong).
+    let fromStep10ModeFailed = false;
+    let fromStep10ModeOut = '';
+    try {
+      execSync(
+        `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 --from-step10 --dry`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      fromStep10ModeFailed = true;
+      fromStep10ModeOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!fromStep10ModeFailed || !fromStep10ModeOut.includes('--from-step10 only applies to --mode handoff')) {
+      console.error('selftest FAIL: --from-step10 with a non-handoff mode must hard-reject at parse time');
+      process.exit(1);
+    }
+
+    let resumeOut;
+    try {
+      resumeOut = execSync(
+        `node "${scriptPath}" --mode handoff --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--gh-notes-file "${notesFile}" --from-step10 --skip-site --dry`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      console.error('selftest FAIL: --mode handoff --from-step10 --dry plan assembly exited non-zero');
+      console.error((e.stdout || '') + (e.stderr || ''));
+      process.exit(1);
+    }
+    const resumeNeed = [
+      '[resume --from-step10] skipping Steps 1/3/4/5/6/7/8/9',
+      'Precondition — verifying release tags already exist and point at HEAD',
+      '[dry] git fetch origin',
+      '=== Step 10 — GH releases + Site deploy',
+    ];
+    for (const marker of resumeNeed) {
+      if (!resumeOut.includes(marker)) {
+        console.error(`selftest FAIL: expected marker not found in --from-step10 dry plan: "${marker}"`);
+        process.exit(1);
+      }
+    }
+    // "=== Step 1" is a prefix of "=== Step 10" — every marker below must
+    // carry enough of its own header to avoid a false positive against the
+    // Step 10 banner this resume path is SUPPOSED to reach.
+    const resumeMustSkip = ['=== Step 1 — Re-baseline', '=== Step 3 — Pre-flight', '=== Step 6 — Tag at HEAD', '=== Step 7 — F-N1', '=== Step 8 — Push', '=== Step 9 — Verify-triggered'];
+    for (const marker of resumeMustSkip) {
+      if (resumeOut.includes(marker)) {
+        console.error(`selftest FAIL: --from-step10 must skip Steps 1-9 — found "${marker}" in the dry plan`);
+        process.exit(1);
+      }
+    }
+
     console.log('selftest OK');
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });