mandrel 1.59.0 → 1.61.0

package/lib/cli/update.js

@@ -3,20 +3,17 @@
  * `mandrel update` subcommand — the auto-update orchestrator (f-update-command,
  * Story #3503, Epic #3437 — Auto-Update & Version Lifecycle).
  *
- * Advances `mandrel` to the newest **non-major** published version,
- * re-materializes `.agents/`, runs applicable version-keyed migrations,
- * surfaces the target changelog, and verifies the result via the doctor
- * registry. A **major** crossing (e.g. `1.x → 2.0`) is gated: the orchestrator
- * refuses to apply it without `--major`, prints a pointer to
- * `docs/upgrade-major.md`, and exits non-zero without touching anything.
+ * Advances `mandrel` to the newest published version, re-materializes
+ * `.agents/`, runs applicable version-keyed migrations, surfaces the target
+ * changelog, and verifies the result via the doctor registry. Major crossings
+ * are applied like any other bump (hard-cutover doctrine —
+ * `.agents/rules/git-conventions.md` § Contract Cutovers).
  *
- * ## Ordered cycle (happy path, non-major bump)
+ * ## Ordered cycle (happy path)
  *
  *   1. resolve target version (newest published) and the current version
- *   2. **major gate** — decline + non-zero exit when the target crosses a
- *      major boundary and `--major` is absent
- *   3. no-op short-circuit — already on the newest version ⇒ nothing to do
- *   4. install        — bump the dependency (lockfile bump left STAGED).
+ *   2. no-op short-circuit — already on the newest version ⇒ nothing to do
+ *   3. install        — bump the dependency (lockfile bump left STAGED).
  *      The package manager is auto-detected from the lockfile in the project
  *      root: `pnpm-lock.yaml` ⇒ `pnpm add -D …` (with `-w` at a
  *      `pnpm-workspace.yaml` root), `yarn.lock` ⇒ `yarn add -D …`, otherwise
@@ -25,10 +22,36 @@
  *      the resolved version so an override can still consume the auto-probed
  *      newest. The registry probe in step 1 always stays on `npm view` (a
  *      PM-agnostic registry query).
- *   5. runSync        — re-materialize ./.agents/ from the new payload
- *   6. runMigrations  — apply version-keyed steps for the crossed range
- *   7. doctor         — run the check registry; success ⇒ all checks pass
- *   8. surface the changelog for the target version
+ *   4. runSync        — re-materialize ./.agents/ **from the newly-installed
+ *      binary** so the materialized payload is always the target version's.
+ *   5. runMigrations  — apply version-keyed steps for the crossed range,
+ *      **from the newly-installed binary**.
+ *   6. doctor         — run the check registry **from the newly-installed
+ *      binary** so `agents-drift` is never a false-green against stale payload.
+ *   7. surface the changelog for the target version
+ *
+ * ## Re-exec of post-install phases (Story #4034)
+ *
+ * Steps 4–6 execute as **child processes spawned from the newly-installed
+ * binary** (`<cwd>/node_modules/.bin/mandrel`) rather than in the running
+ * process. Node cannot hot-swap a `require`d module mid-process, so without
+ * re-exec, the still-running old binary's `runSync`/`runMigrations`/`runDoctor`
+ * code would materialise the old payload even though the package on disk has
+ * already been updated. This produced the silent stale-`.agents/`
+ * materialization and `doctor` false-green observed in the v1.58.0 → v1.59.0
+ * consumer upgrade.
+ *
+ * The orchestration (progress messages, step tracking, changelog surface, exit
+ * code) stays in the parent process; only the version-sensitive phases run from
+ * the new bin. The `spawnPhase` seam makes the child-process boundary fully
+ * injectable so tests can verify the re-exec path without a real npm install.
+ *
+ * Backward compatibility: when `runSync`, `runMigrations`, or `runDoctor`
+ * are explicitly injected (the historical test-seam pattern) and `spawnPhase`
+ * is NOT injected, the in-process seams are used unchanged (old tests stay
+ * green). When `spawnPhase` IS injected, it takes priority over the in-process
+ * seams for the live phases — so new tests targeting the re-exec boundary can
+ * inject `spawnPhase` without touching the old seam interface.
  *
  * ## No git mutation
  *
@@ -43,17 +66,19 @@
  * without invoking any effectful seam (no npm update, no sync, no migrations,
  * no doctor) and writing nothing.
  *
- * ## Major gate
+ * ## Changelog surface
+ *
+ * `defaultSurfaceChangelog` prints the `docs/CHANGELOG.md` section(s) for the
+ * applied range `(current, target]`. It resolves the file against the target
+ * version's install directory (the freshly bumped `node_modules/mandrel/`),
+ * where the changelog is now included in the published tarball
+ * (`docs/CHANGELOG.md` in the `files` allowlist — Story #4035).
  *
- * The project sits on the **1.x** line under release-please
- * `always-bump-minor` ([AGENTS.md § Major-version policy]); a major release is
- * a deliberate manual operator decision, so adopting one must be equally
- * deliberate. When the newest version's major exceeds the current major:
- *   - **without `--major`**: print the available version + the
- *     `docs/upgrade-major.md` runbook pointer, exit non-zero, and invoke
- *     **no** npm-update / sync / migration / doctor seam.
- *   - **with `--major`**: apply the major target and print the runbook inline.
- * Routine minor/patch bumps within the 1.x line are never gated.
+ * When the packaged file is absent (e.g. an older installed version predating
+ * Story #4035), the seam attempts a one-shot HTTP GET of the raw file from
+ * GitHub via the injectable `fetchChangelog` seam. If that fetch also fails,
+ * the seam degrades gracefully — never throwing — and emits an actionable
+ * message directing the operator to the GitHub Releases page.
  *
  * ## Injectable seams (used by lib/cli/__tests__/update*.test.js)
  *
@@ -62,15 +87,27 @@
  *   - `resolveTargetVersion`— async, returns the newest published version
  *   - `npmUpdate`           — async, performs the dependency bump (no git);
  *                             receives `(target, { installCmd })`
- *   - `runSync`             — re-materializes ./.agents/ (lib/cli/sync.js)
- *   - `runMigrations`       — version-keyed migration runner (lib/migrations)
- *   - `runDoctor`           — async, returns { ok, results } from the registry
+ *   - `spawnPhase`          — async, spawns a post-install phase from the new
+ *                             binary; receives `(phase, args, { binPath, cwd })`
+ *                             and returns `{ ok, stdout, stderr }`. When
+ *                             injected, it takes priority over `runSync`,
+ *                             `runMigrations`, and `runDoctor` for the live
+ *                             phases. See § Re-exec of post-install phases.
+ *   - `runSync`             — re-materializes ./.agents/ (lib/cli/sync.js).
+ *                             Used when `spawnPhase` is NOT injected (backward
+ *                             compat for tests that pre-date Story #4034).
+ *   - `runMigrations`       — version-keyed migration runner (lib/migrations).
+ *                             Used when `spawnPhase` is NOT injected.
+ *   - `runDoctor`           — async, returns { ok, results } from the registry.
+ *                             Used when `spawnPhase` is NOT injected.
  *   - `surfaceChangelog`    — emits the target changelog section
  *   - `write` / `writeErr`  — stdout / stderr sinks
  *   - `exit`                — process.exit replacement
+ *   - `cwd`                 — process.cwd() replacement (used to resolve the
+ *                             new binary path when `spawnPhase` is absent)
  *
  * Security (security-baseline § 5 — Data Leakage & Logging): logs only version
- * strings, step names, and the runbook path. No tokens, credentials, or env
+ * strings and step names. No tokens, credentials, or env
  * values are read or logged; no shell-string interpolation occurs here (the
  * npm bump is delegated to the injected `npmUpdate` seam, which owns transport).
  *
@@ -86,72 +123,46 @@
  * the install argv is a tokenized list whose only variable segment is a
  * resolved semver string — see `lib/install-cmd-parser.js` for the shared
  * tokenize-and-spawn rationale this module reuses (no duplicated workaround).
+ *
+ * The `spawnPhase` default (Story #4034) similarly uses `shell: true` only on
+ * Windows: the new binary resolves from `node_modules/.bin/mandrel` (a fixed,
+ * non-operator-supplied path) and the per-phase argv vector is a constant
+ * fixed list (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`,
+ * `['doctor']`) with no injection risk regardless of the shell flag.
  */
 
 import { spawnSync } from 'node:child_process';
 import nodeFs from 'node:fs';
+import nodeHttps from 'node:https';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { detectPackageManagerWithWorkspace } from '../../.agents/scripts/lib/detect-package-manager.js';
 import { runInstallCommand } from '../../.agents/scripts/lib/install-cmd-parser.js';
 import { runMigrations as defaultRunMigrations } from '../migrations/index.js';
 import { registry } from './registry.js';
 import { runSync as defaultRunSync } from './sync.js';
 import { isStale } from './version-check.js';
-
-/** Path (relative to project root) of the major-upgrade runbook. */
-const RUNBOOK_PATH = 'docs/upgrade-major.md';
+import { compareVersions } from './version-helpers.js';
 
 /** The published package whose newest version `mandrel update` advances to. */
 const PACKAGE_NAME = 'mandrel';
 
-/** Default freshness-cache filename — mirrors version-check.js. */
-const DEFAULT_CACHE_FILENAME = 'version-check.json';
-
 /**
- * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
- * missing segments coerce to 0 so a partial version still compares sanely.
- *
- * @param {string} version
- * @returns {[number, number, number]}
+ * GitHub raw-file base URL for fetching `docs/CHANGELOG.md` when the packaged
+ * file is absent (Story #4035 — GitHub fallback). Resolves to the tagged
+ * release, e.g. `.../mandrel-v1.59.0/docs/CHANGELOG.md`.
  */
-function parseVersion(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
-}
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/dsj1984/mandrel/';
 
 /**
- * Compare two version strings. Negative when `a < b`, zero when equal,
- * positive when `a > b` (the standard `Array.sort` comparator contract).
- *
- * @param {string} a
- * @param {string} b
- * @returns {number}
+ * Human-readable GitHub Releases page — surfaced in the actionable fallback
+ * message when neither the packaged file nor the GitHub fetch succeeds.
  */
-function compareVersions(a, b) {
-  const pa = parseVersion(a);
-  const pb = parseVersion(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
-  }
-  return 0;
-}
+const GITHUB_RELEASES_URL = 'https://github.com/dsj1984/mandrel/releases';
 
-/**
- * True when `target`'s major axis is strictly greater than `current`'s — the
- * gated "crosses a major boundary" condition.
- *
- * @param {string} current
- * @param {string} target
- * @returns {boolean}
- */
-function crossesMajor(current, target) {
-  return parseVersion(target)[0] > parseVersion(current)[0];
-}
+/** Default freshness-cache filename — mirrors version-check.js. */
+const DEFAULT_CACHE_FILENAME = 'version-check.json';
 
 /**
  * Resolve the installed `mandrel` version from this package's own
@@ -183,12 +194,15 @@ function resolveProjectRoot() {
  * Default `resolveTargetVersion` seam: determine the newest published
  * `mandrel` version via the daily freshness cache (`version-check.js`).
  *
- * This delegates to `isStale`, which honours the 24h-cache semantics: a fresh
- * cache returns the cached version with **zero** network I/O, while a missing,
- * corrupt, or stale cache triggers exactly one network probe (`npm view
- * mandrel version`) and refreshes `temp/version-check.json`. Wiring the
- * production update path through `isStale` is precisely what populates that
- * daily cache, which the `version-current` doctor advisory reads.
+ * When `bypassCache` is `true` (the default for an explicit `mandrel update`
+ * call — Story #4046 A1b), the cache freshness window is effectively zeroed by
+ * passing `now` as far in the future, which makes `isStale` treat any existing
+ * cache as stale and always issue exactly one network probe. The cache is still
+ * written so the post-update `version-current` advisory has a fresh baseline.
+ *
+ * When `bypassCache` is `false` (passive staleness checks only), the normal
+ * 24h-cache semantics apply: a fresh cache returns the cached version with
+ * zero network I/O.
  *
  * The network probe shells `npm view` through `spawnSync` with a fixed argument
  * vector (no shell-string interpolation; the package name is a constant). On
@@ -202,6 +216,7 @@ function resolveProjectRoot() {
  *   fs?: typeof nodeFs,
  *   runner?: () => string,
  *   now?: Date,
+ *   bypassCache?: boolean,
  *   log?: (msg: string) => void,
  * }} [opts]
  * @returns {Promise<string>} The newest published version string.
@@ -211,9 +226,22 @@ async function defaultResolveTargetVersion({
   fs = nodeFs,
   runner = defaultVersionRunner,
   now = new Date(),
+  bypassCache = false,
   log = () => {},
 } = {}) {
-  const result = await isStale({ cachePath, now, runner, fs, log });
+  // When bypassCache is true, push `now` far enough into the future that any
+  // cached checkedAt value is guaranteed to be older than the STALE_AFTER_MS
+  // window, forcing a fresh network probe (Story #4046 A1b).
+  const effectiveNow = bypassCache
+    ? new Date(now.getTime() + 48 * 60 * 60 * 1000)
+    : now;
+  const result = await isStale({
+    cachePath,
+    now: effectiveNow,
+    runner,
+    fs,
+    log,
+  });
   return String(result.latestVersion);
 }
 
@@ -280,28 +308,30 @@ function repairInstallCommand(packageManager) {
  * Detecting the lockfile keeps the bump on the operator's real package manager
  * so the change lands in the matching lockfile.
  *
+ * Delegates to the shared `detectPackageManagerWithWorkspace` helper
+ * (Story #4048 B3 — one implementation per concept). The `fs` seam is adapted
+ * to the shared module's `exists` contract; the shared module's `bun` return
+ * value coerces to `npm` here because `bun add` is not yet a first-class update
+ * path for this orchestrator.
+ *
  * @param {string} [cwd] - Project root to probe (default `process.cwd()`).
  * @param {typeof nodeFs} [fs]
  * @returns {{ packageManager: 'pnpm' | 'yarn' | 'npm', workspaceRoot: boolean }}
  */
 export function detectPackageManager(cwd = process.cwd(), fs = nodeFs) {
-  const has = (file) => {
+  const exists = (p) => {
     try {
-      return fs.existsSync(path.join(cwd, file));
+      return fs.existsSync(p);
     } catch {
       return false;
     }
   };
-  if (has('pnpm-lock.yaml')) {
-    return {
-      packageManager: 'pnpm',
-      workspaceRoot: has('pnpm-workspace.yaml'),
-    };
-  }
-  if (has('yarn.lock')) {
-    return { packageManager: 'yarn', workspaceRoot: false };
-  }
-  return { packageManager: 'npm', workspaceRoot: false };
+  const result = detectPackageManagerWithWorkspace(cwd, exists);
+  // Coerce `bun` → `npm` because this orchestrator's install-command builder
+  // only handles pnpm / yarn / npm today.
+  const packageManager =
+    result.packageManager === 'bun' ? 'npm' : result.packageManager;
+  return { packageManager, workspaceRoot: result.workspaceRoot };
 }
 
 /**
@@ -408,6 +438,72 @@ export function defaultNpmUpdate(
   }
 }
 
+/**
+ * Fetch `docs/CHANGELOG.md` for a specific mandrel tag from GitHub's raw
+ * content endpoint. This is the fallback when the packaged file is absent
+ * (e.g. an older install predating Story #4035 which added the file to the
+ * npm `files` allowlist).
+ *
+ * Injectable via the `fetchChangelog` seam so tests can verify the fallback
+ * path without issuing real network calls.
+ *
+ * The tag shape follows the `mandrel-vX.Y.Z` namespace (namespaced at
+ * `mandrel-v1.44.0`; bare `vX.Y.Z` for earlier releases). This function
+ * tries the namespaced tag first, then the bare-tag form, so it covers both
+ * tag series without forcing callers to know the boundary.
+ *
+ * Security (security-baseline § Transport & Headers): the URL is constructed
+ * from a constant base and a semver string — no user input, no shell
+ * interpolation. The GET is a read-only fetch with no credentials.
+ *
+ * @param {string} version - The target semver string (e.g. `"1.59.0"`).
+ * @param {{
+ *   https?: typeof nodeHttps,
+ * }} [deps]
+ * @returns {Promise<string>} The raw changelog text.
+ * @throws {Error} When both tag forms return a non-2xx response or the request
+ *   errors out — the caller handles this gracefully.
+ */
+export async function fetchChangelogFromGitHub(
+  version,
+  { https: httpsImpl = nodeHttps } = {},
+) {
+  const tags = [`mandrel-v${version}`, `v${version}`];
+
+  /**
+   * @param {string} url
+   * @returns {Promise<{ status: number, body: string }>}
+   */
+  const httpGet = (url) =>
+    new Promise((resolve, reject) => {
+      httpsImpl
+        .get(url, (res) => {
+          const chunks = [];
+          res.on('data', (d) => chunks.push(d));
+          res.on('end', () =>
+            resolve({
+              status: res.statusCode ?? 0,
+              body: Buffer.concat(chunks).toString('utf8'),
+            }),
+          );
+        })
+        .on('error', reject);
+    });
+
+  for (const tag of tags) {
+    const url = `${GITHUB_RAW_BASE}${tag}/docs/CHANGELOG.md`;
+    // eslint-disable-next-line no-await-in-loop
+    const { status, body } = await httpGet(url);
+    if (status >= 200 && status < 300) {
+      return body;
+    }
+  }
+
+  throw new Error(
+    `mandrel update: GitHub fetch for mandrel v${version} docs/CHANGELOG.md returned non-2xx for all tag forms (tried: ${tags.join(', ')})`,
+  );
+}
+
 /**
  * Default `surfaceChangelog` seam: print the `docs/CHANGELOG.md` section(s)
  * covering the applied version range `(current, target]`. The changelog is
@@ -415,38 +511,61 @@ export function defaultNpmUpdate(
  * prints every section whose version is newer than `current` and no newer than
  * `target`.
  *
- * Degrades gracefully (warns, never throws) when the file is absent or no
- * matching section is found — surfacing the changelog is best-effort and must
- * never fail an otherwise-successful upgrade.
+ * Resolution order (Story #4035):
+ *   1. Read `docs/CHANGELOG.md` from the target version's install directory
+ *      (`node_modules/mandrel/docs/CHANGELOG.md` — now in the published
+ *      tarball since `package.json` lists `docs/CHANGELOG.md` in `files`).
+ *   2. When the packaged file is absent (older install), fetch it from GitHub
+ *      via the injectable `fetchChangelog` seam.
+ *   3. When both sources fail, emit an actionable warning with a link to the
+ *      GitHub Releases page — never a bare "not found … skipping".
+ *
+ * Degrades gracefully (warns, never throws) — surfacing the changelog is
+ * best-effort and must never fail an otherwise-successful upgrade.
  *
  * @param {string} target - The applied target version.
  * @param {{
  *   current?: string,
  *   changelogPath?: string,
  *   fs?: typeof nodeFs,
+ *   fetchChangelog?: (version: string) => Promise<string>,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  * }} [opts]
- * @returns {void}
+ * @returns {Promise<void>}
  */
-function defaultSurfaceChangelog(
+async function defaultSurfaceChangelog(
   target,
   {
     current,
     changelogPath = path.join(resolveProjectRoot(), 'docs', 'CHANGELOG.md'),
     fs = nodeFs,
+    fetchChangelog = fetchChangelogFromGitHub,
     write = (s) => process.stdout.write(s),
     writeErr = (s) => process.stderr.write(s),
   } = {},
 ) {
   let raw;
+
+  // 1. Try the packaged file (present in installs since Story #4035).
   try {
     raw = fs.readFileSync(changelogPath, 'utf8');
   } catch {
-    writeErr(
-      `mandrel update: changelog not found at ${changelogPath} — skipping changelog surface.\n`,
-    );
-    return;
+    // File absent — fall through to GitHub fetch.
+  }
+
+  // 2. Packaged file absent: attempt a GitHub fetch for the target tag.
+  if (raw === undefined) {
+    try {
+      raw = await fetchChangelog(target);
+    } catch {
+      // Both sources unavailable — emit an actionable message and return.
+      writeErr(
+        `mandrel update: changelog not available for v${target} — ` +
+          `view the release notes at ${GITHUB_RELEASES_URL}\n`,
+      );
+      return;
+    }
   }
 
   const sections = parseChangelogSections(raw);
@@ -458,7 +577,8 @@ function defaultSurfaceChangelog(
 
   if (relevant.length === 0) {
     writeErr(
-      `mandrel update: no CHANGELOG section found for v${target} — skipping changelog surface.\n`,
+      `mandrel update: no CHANGELOG section found for v${target} — ` +
+        `view the release notes at ${GITHUB_RELEASES_URL}\n`,
     );
     return;
   }
@@ -509,6 +629,8 @@ function parseChangelogSections(raw) {
  * report whether all passed. Mirrors lib/cli/doctor.js's pass accounting
  * without the formatted report (the orchestrator owns its own output).
  *
+ * This is used only when `spawnPhase` is NOT injected (backward-compat path).
+ *
  * @param {{ checks?: typeof registry }} [opts]
  * @returns {Promise<{ ok: boolean, results: Array<{ name: string, ok: boolean }> }>}
  */
@@ -522,10 +644,88 @@ async function defaultRunDoctor({ checks = registry } = {}) {
 }
 
 /**
- * The ordered step names the orchestrator drives on a non-major bump. Shared
+ * Resolve the path to the `mandrel` binary inside `node_modules/.bin/` for the
+ * given project root. On Windows the binary is a `.cmd` shim; on POSIX it is a
+ * plain executable. The resolved path is used as the target for the post-install
+ * phase re-exec (Story #4034).
+ *
+ * @param {string} projectRoot - Absolute path to the consumer project.
+ * @returns {string} Absolute path to the new binary.
+ */
+export function resolveNewBinPath(projectRoot) {
+  const binName = process.platform === 'win32' ? 'mandrel.cmd' : 'mandrel';
+  return path.join(projectRoot, 'node_modules', '.bin', binName);
+}
+
+/**
+ * Default `spawnPhase` seam (Story #4034): spawn a post-install phase from the
+ * newly-installed `mandrel` binary and stream its stdout/stderr through the
+ * parent's write sinks. Each phase runs as an isolated child process so the
+ * newly-installed module code (not the currently-loaded old module) executes.
+ *
+ * The spawn uses `shell: true` only on Windows where the binary is a `.cmd`
+ * shim (CVE-2024-27980 parity). The argv vector is a fixed constant list
+ * per phase — no operator-supplied data enters the vector, so the shell flag
+ * carries no injection risk (security-baseline § Output & Rendering).
+ *
+ * Throws when the child exits non-zero so the orchestrator can surface the
+ * failure to the operator.
+ *
+ * @param {string} phase - The mandrel sub-command to run (e.g. `'sync'`).
+ * @param {string[]} args - Additional arguments for the sub-command.
+ * @param {{
+ *   binPath: string,
+ *   cwd: string,
+ *   write: (s: string) => void,
+ *   writeErr: (s: string) => void,
+ *   spawnFn?: typeof spawnSync,
+ * }} opts
+ * @returns {{ ok: boolean, stdout: string, stderr: string }}
+ */
+export function defaultSpawnPhase(
+  phase,
+  args,
+  { binPath, cwd, write, writeErr, spawnFn = spawnSync },
+) {
+  const argv = [phase, ...args];
+  const r = spawnFn(binPath, argv, {
+    cwd,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  const stdout = typeof r.stdout === 'string' ? r.stdout : '';
+  const stderr = typeof r.stderr === 'string' ? r.stderr : '';
+  if (stdout) write(stdout);
+  if (stderr) writeErr(stderr);
+  if (r.error) {
+    throw new Error(
+      `mandrel update: failed to spawn \`mandrel ${phase}\` from new binary: ${r.error.message}`,
+    );
+  }
+  const ok = r.status === 0;
+  return { ok, stdout, stderr };
+}
+
+/**
+ * The ordered step names the orchestrator drives on an update. Shared
  * by the live path and the `--dry-run` plan printout so the two never drift.
+ *
+ * Step ordering (Story #4046 A1c):
+ *   1. npm-update     — install the new version
+ *   2. runSync        — re-materialize .agents/ from the new payload
+ *   3. sync-commands  — regenerate .claude/commands/ from the new payload
+ *   4. runMigrations  — apply version-keyed migrations
+ *   5. doctor         — validate the post-upgrade state
+ *   6. surface changelog — print the changelog (always last, best-effort)
  */
-const STEP_PLAN = ['npm-update', 'runSync', 'runMigrations', 'doctor'];
+const STEP_PLAN = [
+  'npm-update',
+  'runSync',
+  'sync-commands',
+  'runMigrations',
+  'doctor',
+  'surface changelog',
+];
 
 /**
  * Extract the `--install-cmd "<cmd>"` value from the subcommand argv. Accepts
@@ -553,21 +753,6 @@ function parseInstallCmdFlag(argv) {
   return undefined;
 }
 
-/**
- * Print the major-gate refusal: the available version, the runbook pointer,
- * and the re-run hint. No effectful seam runs after this.
- *
- * @param {string} target
- * @param {(s: string) => void} writeErr
- */
-function emitMajorRefusal(target, writeErr) {
-  writeErr(
-    `mandrel update: a newer MAJOR version (${target}) is available; ` +
-      'this is a breaking upgrade.\n' +
-      `   → Review ${RUNBOOK_PATH}, then re-run with --major to apply it.\n`,
-  );
-}
-
 /**
  * Run the `mandrel update` orchestration cycle.
  *
@@ -576,6 +761,7 @@ function emitMajorRefusal(target, writeErr) {
  *   currentVersion?: string | (() => string),
  *   resolveTargetVersion?: () => (string | Promise<string>),
  *   npmUpdate?: (version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>,
+ *   spawnPhase?: (phase: string, args: string[], opts: { binPath: string, cwd: string, write: (s: string) => void, writeErr: (s: string) => void }) => Promise<{ ok: boolean, stdout: string, stderr: string }> | { ok: boolean, stdout: string, stderr: string },
  *   runSync?: typeof defaultRunSync,
  *   runMigrations?: typeof defaultRunMigrations,
  *   runDoctor?: typeof defaultRunDoctor,
@@ -583,13 +769,13 @@ function emitMajorRefusal(target, writeErr) {
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
+ *   cwd?: () => string,
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
- *   action: 'updated' | 'declined-major' | 'dry-run' | 'up-to-date' | 'doctor-failed',
+ *   action: 'updated' | 'dry-run' | 'up-to-date' | 'doctor-failed',
  *   currentVersion: string,
  *   targetVersion: string | null,
- *   major: boolean,
  *   stepsRun: string[],
  *   dryRun: boolean,
  * }>}
@@ -599,6 +785,7 @@ export async function runUpdate({
   currentVersion,
   resolveTargetVersion,
   npmUpdate,
+  spawnPhase,
   runSync = defaultRunSync,
   runMigrations = defaultRunMigrations,
   runDoctor = defaultRunDoctor,
@@ -606,9 +793,9 @@ export async function runUpdate({
   write = (s) => process.stdout.write(s),
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
+  cwd = () => process.cwd(),
 } = {}) {
   const dryRun = argv.includes('--dry-run');
-  const allowMajor = argv.includes('--major');
   const installCmd = parseInstallCmdFlag(argv);
 
   const current =
@@ -623,25 +810,6 @@ export async function runUpdate({
   }
   const target = String(await resolveTargetVersion());
 
-  const major = crossesMajor(current, target);
-
-  // --- Major gate -----------------------------------------------------------
-  // A major crossing without --major is refused outright: no npm-update, no
-  // sync, no migration, no doctor — print the runbook pointer and exit non-zero.
-  if (major && !allowMajor) {
-    emitMajorRefusal(target, writeErr);
-    exit(1);
-    return {
-      ok: false,
-      action: 'declined-major',
-      currentVersion: current,
-      targetVersion: target,
-      major: true,
-      stepsRun: [],
-      dryRun,
-    };
-  }
-
   // --- No-op short-circuit --------------------------------------------------
   // Already on (or ahead of) the newest version: nothing to apply.
   if (compareVersions(target, current) <= 0) {
@@ -651,7 +819,6 @@ export async function runUpdate({
       action: 'up-to-date',
       currentVersion: current,
       targetVersion: target,
-      major,
       stepsRun: [],
       dryRun,
     };
@@ -662,34 +829,21 @@ export async function runUpdate({
   // write nothing to disk.
   if (dryRun) {
     write(`mandrel update — planned upgrade v${current} → v${target}\n`);
-    if (major) {
-      write('  (major upgrade — --major supplied)\n');
-    }
     STEP_PLAN.forEach((step, i) => {
       write(`  ${i + 1}. ${step}\n`);
     });
-    write('  5. surface changelog\n');
     write('Dry run: no files written, no dependency bumped.\n');
     return {
       ok: true,
       action: 'dry-run',
       currentVersion: current,
       targetVersion: target,
-      major,
       stepsRun: [],
       dryRun: true,
     };
   }
 
-  // --- Major runbook (inline, when --major applies) -------------------------
-  if (major) {
-    write(
-      `Applying MAJOR upgrade v${current} → v${target} (--major). ` +
-        `Review the runbook: ${RUNBOOK_PATH}\n`,
-    );
-  } else {
-    write(`Updating v${current} → v${target}…\n`);
-  }
+  write(`Updating v${current} → v${target}…\n`);
 
   const stepsRun = [];
 
@@ -703,40 +857,159 @@ export async function runUpdate({
   await npmUpdate(target, { installCmd });
   stepsRun.push('npm-update');
 
-  // 2. runSync — re-materialize ./.agents/ from the freshly installed payload.
-  runSync({ argv: [] });
-  stepsRun.push('runSync');
+  // Decide whether to use the re-exec path (spawnPhase) or the in-process
+  // backward-compat seams (runSync / runMigrations / runDoctor).
+  //
+  // spawnPhase injected → re-exec path: all post-install phases run from the
+  //   newly-installed binary. This is the production path and is what fixes
+  //   the stale-materialization bug (Story #4034).
+  //
+  // spawnPhase NOT injected → in-process path: the original pre-Story-#4034
+  //   behaviour. Tests that pre-date this change inject runSync/runMigrations/
+  //   runDoctor and rely on the in-process path; they stay green without any
+  //   modification.
+  const useReExec = typeof spawnPhase === 'function';
 
-  // 3. runMigrations — apply version-keyed steps for the crossed range.
-  runMigrations({ fromVersion: current, toVersion: target, ctx: {} });
-  stepsRun.push('runMigrations');
+  if (useReExec) {
+    // Re-exec path: post-install phases run from the new binary.
+    const projectRoot = cwd();
+    const binPath = resolveNewBinPath(projectRoot);
 
-  // 4. doctor — verify the resulting install.
-  const doctor = await runDoctor();
-  stepsRun.push('doctor');
+    // 2. runSync from new bin — re-materialize ./.agents/ from the freshly
+    //    installed payload. Running from the new bin ensures the copied files
+    //    come from the new package's .agents/ tree, not the old loaded module.
+    const syncResult = await spawnPhase('sync', [], {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    if (!syncResult.ok) {
+      throw new Error(
+        `mandrel update: \`mandrel sync\` from new binary exited non-zero — ` +
+          'the .agents/ materialization may be incomplete. ' +
+          'Run `mandrel sync` manually to restore.',
+      );
+    }
+    stepsRun.push('runSync');
 
-  // 5. surface the target changelog (best-effort; optional seam).
-  if (typeof surfaceChangelog === 'function') {
-    await surfaceChangelog(target);
-  }
+    // 3. sync-commands from new bin — regenerate .claude/commands/ from the
+    //    freshly-materialized .agents/workflows/. Running from the new bin
+    //    ensures the command tree is consistent with the new payload; an
+    //    upstream-renamed workflow will be projected correctly and the old
+    //    command file will be reaped. This step must follow runSync so the
+    //    workflow sources are up to date before the command tree is rebuilt
+    //    (Story #4046 A1c — `commands-in-sync` validates the post-sync state).
+    const syncCommandsResult = await spawnPhase('sync-commands', [], {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    if (!syncCommandsResult.ok) {
+      throw new Error(
+        `mandrel update: \`mandrel sync-commands\` from new binary exited non-zero — ` +
+          'the .claude/commands/ tree may be out of sync. ' +
+          'Run `npm run sync:commands` manually to restore.',
+      );
+    }
+    stepsRun.push('sync-commands');
 
-  if (!doctor.ok) {
-    const failed = doctor.results.filter((r) => !r.ok).map((r) => r.name);
-    writeErr(
-      `mandrel update: upgraded to v${target} but doctor reported failures: ` +
-        `${failed.join(', ')}\n` +
-        '   → Run `mandrel doctor` for remedies.\n',
+    // 4. runMigrations from new bin — apply version-keyed steps for the
+    //    crossed range. The new binary's migration registry contains any steps
+    //    added in the target version; the old process's registry does not.
+    const migrateResult = await spawnPhase(
+      'migrate',
+      ['--from', current, '--to', target],
+      { binPath, cwd: projectRoot, write, writeErr },
     );
-    exit(1);
-    return {
-      ok: false,
-      action: 'doctor-failed',
-      currentVersion: current,
-      targetVersion: target,
-      major,
-      stepsRun,
-      dryRun: false,
-    };
+    if (!migrateResult.ok) {
+      throw new Error(
+        `mandrel update: \`mandrel migrate\` from new binary exited non-zero — ` +
+          `some migrations for v${current} → v${target} may not have applied. ` +
+          `Run \`mandrel migrate --from ${current} --to ${target}\` manually to retry.`,
+      );
+    }
+    stepsRun.push('runMigrations');
+
+    // 5. doctor from new bin — verify the resulting install. Running from the
+    //    new bin is critical: the agents-drift check compares the materialized
+    //    .agents/ against the installed package payload. When the old process
+    //    runs this check, it resolves the package root to its own (old) install
+    //    dir, so drift against the new payload is invisible. The new binary
+    //    resolves the package root to the now-installed new version, producing
+    //    an accurate result.
+    const doctorResult = await spawnPhase('doctor', [], {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    stepsRun.push('doctor');
+
+    // 6. surface the target changelog (best-effort; optional seam).
+    if (typeof surfaceChangelog === 'function') {
+      await surfaceChangelog(target);
+    }
+
+    if (!doctorResult.ok) {
+      writeErr(
+        `mandrel update: upgraded to v${target} but doctor reported failures.\n` +
+          '   → Run `mandrel doctor` for remedies.\n',
+      );
+      exit(1);
+      return {
+        ok: false,
+        action: 'doctor-failed',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun,
+        dryRun: false,
+      };
+    }
+  } else {
+    // In-process backward-compat path (pre-Story-#4034 behaviour).
+    // Used when no `spawnPhase` seam is injected — preserves full backward
+    // compatibility with existing tests that inject runSync/runMigrations/
+    // runDoctor directly.
+
+    // 2. runSync — re-materialize ./.agents/ from the new payload.
+    runSync({ argv: [] });
+    stepsRun.push('runSync');
+
+    // 3. runMigrations — apply version-keyed steps for the crossed range.
+    // Note: the in-process path (pre-Story-#4034) does not run sync-commands
+    // here because sync-commands runs as a child process and there is no
+    // in-process seam for it. The re-exec path (spawnPhase) handles it.
+    runMigrations({ fromVersion: current, toVersion: target, ctx: {} });
+    stepsRun.push('runMigrations');
+
+    // 4. doctor — verify the resulting install.
+    const doctor = await runDoctor();
+    stepsRun.push('doctor');
+
+    // 5. surface the target changelog (best-effort; optional seam).
+    if (typeof surfaceChangelog === 'function') {
+      await surfaceChangelog(target);
+    }
+
+    if (!doctor.ok) {
+      const failed = doctor.results.filter((r) => !r.ok).map((r) => r.name);
+      writeErr(
+        `mandrel update: upgraded to v${target} but doctor reported failures: ` +
+          `${failed.join(', ')}\n` +
+          '   → Run `mandrel doctor` for remedies.\n',
+      );
+      exit(1);
+      return {
+        ok: false,
+        action: 'doctor-failed',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun,
+        dryRun: false,
+      };
+    }
   }
 
   write(`✅  Updated to v${target}. The lockfile bump is staged for review.\n`);
@@ -745,7 +1018,6 @@ export async function runUpdate({
     action: 'updated',
     currentVersion: current,
     targetVersion: target,
-    major,
     stepsRun,
     dryRun: false,
   };
@@ -755,26 +1027,37 @@ export async function runUpdate({
  * Default export consumed by `bin/mandrel.js`.
  *
  * Wires the production-default seams that `runUpdate` leaves injectable:
- *   - `resolveTargetVersion` probes the newest published `mandrel`
- *     version through the daily freshness cache (`version-check.js#isStale`),
- *     which ALSO populates `temp/version-check.json` — the cache the
- *     `version-current` doctor advisory reads.
+ *   - `resolveTargetVersion` always probes the registry via `isStale` with
+ *     `bypassCache: true` — the 24h cache is overridden for explicit update
+ *     calls so the resolved version is always fresh (Story #4046 A1b). The
+ *     cache is still written so the `version-current` doctor advisory reads
+ *     a current baseline after the upgrade.
  *   - `npmUpdate` runs the install command — auto-detected from the project
  *     lockfile (`pnpm`/`yarn`/`npm`), or the `--install-cmd` override —
  *     through the shared `runInstallCommand` helper — no git mutation;
  *     lockfile left staged.
+ *   - `spawnPhase` is wired to `defaultSpawnPhase`, which spawns each
+ *     post-install phase (sync, sync-commands, migrate, doctor) from the
+ *     newly-installed binary (`node_modules/.bin/mandrel`). This is the
+ *     Story #4034 fix: the new bin loads the new package's module code and
+ *     resolves paths against the new install dir, so these phases can never
+ *     observe the old payload.
  *   - `surfaceChangelog` prints the relevant `docs/CHANGELOG.md` section(s)
- *     for the applied range, degrading gracefully when the file is absent.
+ *     for the applied range. Reads from the packaged file first; falls back to
+ *     a GitHub raw-content fetch via the injectable `fetchChangelog` seam when
+ *     the packaged file is absent; emits an actionable link to the GitHub
+ *     Releases page when both sources fail (Story #4035).
  *
  * Every seam stays injectable on `runUpdate`; these are merely the
  * no-seam-provided fallbacks, so the existing seam-driven tests stay green.
- * `--major` / `--dry-run` / `--install-cmd` are parsed from `argv` by
+ * `--dry-run` / `--install-cmd` are parsed from `argv` by
  * `runUpdate` itself.
  *
  * The second `deps` argument exposes the **process boundaries** the production
  * defaults shell out across (`versionRunner` = `npm view`, `runInstall` =
- * the install spawn) plus `fs` / `cachePath` / `now`, so the entrypoint can be
- * driven end-to-end with the network/npm boundary stubbed and no real I/O.
+ * the install spawn, `spawnFn` = the phase-spawn boundary) plus `fs` /
+ * `cachePath` / `now`, so the entrypoint can be driven end-to-end with the
+ * network/npm boundary stubbed and no real I/O.
  * `bin/mandrel.js` calls `run(argv)` with no `deps`, getting the production
  * wiring; tests pass fakes. The `deps` surface is NOT part of the public
  * subcommand contract — `bin/mandrel.js` only ever supplies `argv`.
@@ -787,7 +1070,9 @@ export async function runUpdate({
  *   now?: Date,
  *   versionRunner?: () => string,
  *   runInstall?: (installCmd: string, cwd: string) => { status: number, stderr: string },
+ *   spawnFn?: typeof spawnSync,
  *   changelogPath?: string,
+ *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
  *   runSync?: typeof defaultRunSync,
  *   runMigrations?: typeof defaultRunMigrations,
@@ -806,49 +1091,78 @@ export default async function run(argv = [], deps = {}) {
     now,
     versionRunner,
     runInstall,
+    spawnFn,
     changelogPath,
+    fetchChangelog,
     runUpdate: runUpdateImpl = runUpdate,
     runSync,
     runMigrations,
     runDoctor,
-    write,
-    writeErr,
-    exit,
+    write = (s) => process.stdout.write(s),
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
     log,
   } = deps;
 
   const current = deps.currentVersion ?? defaultCurrentVersion(fs);
 
+  // The production spawnPhase default: spawn each post-install phase from
+  // node_modules/.bin/mandrel (the newly-installed binary). spawnFn is
+  // injectable so tests can stub the spawn boundary without running a real
+  // child process.
+  const productionSpawnPhase = (phase, args, opts) =>
+    defaultSpawnPhase(phase, args, {
+      ...opts,
+      ...(spawnFn ? { spawnFn } : {}),
+    });
+
+  // Resolve which seam set to use for post-install phases. If any old-style
+  // in-process seam (runSync/runMigrations/runDoctor) is injected, fall back
+  // to the pre-Story-#4034 in-process path so the entrypoint test stays green.
+  // Otherwise use the re-exec path (spawnPhase). This is a single ternary
+  // rather than stacked optional spreads (tidy, Story #4046).
+  const phaseSeams =
+    runSync || runMigrations || runDoctor
+      ? {
+          ...(runSync ? { runSync } : {}),
+          ...(runMigrations ? { runMigrations } : {}),
+          ...(runDoctor ? { runDoctor } : {}),
+        }
+      : { spawnPhase: productionSpawnPhase };
+
   await runUpdateImpl({
     argv,
     currentVersion: current,
+    // Always bypass the 24h cache on an explicit `mandrel update` so the
+    // resolved target is fresh from the registry (Story #4046 A1b).
     resolveTargetVersion: () =>
       defaultResolveTargetVersion({
-        ...(cachePath ? { cachePath } : {}),
+        cachePath:
+          cachePath ?? path.join(process.cwd(), 'temp', DEFAULT_CACHE_FILENAME),
         fs,
-        ...(versionRunner ? { runner: versionRunner } : {}),
-        ...(now ? { now } : {}),
-        ...(log ? { log } : {}),
+        runner: versionRunner ?? defaultVersionRunner,
+        now: now ?? new Date(),
+        bypassCache: true,
+        log: log ?? (() => {}),
       }),
     npmUpdate: (target, { installCmd } = {}) =>
       defaultNpmUpdate(target, {
         ...(installCmd ? { installCmd } : {}),
-        ...(runInstall ? { runInstall } : {}),
+        runInstall: runInstall ?? runInstallCommand,
         fs,
       }),
+    ...phaseSeams,
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
         current,
         fs,
         ...(changelogPath ? { changelogPath } : {}),
-        ...(write ? { write } : {}),
-        ...(writeErr ? { writeErr } : {}),
+        fetchChangelog: fetchChangelog ?? fetchChangelogFromGitHub,
+        write,
+        writeErr,
       }),
-    ...(runSync ? { runSync } : {}),
-    ...(runMigrations ? { runMigrations } : {}),
-    ...(runDoctor ? { runDoctor } : {}),
-    ...(write ? { write } : {}),
-    ...(writeErr ? { writeErr } : {}),
-    ...(exit ? { exit } : {}),
+    write,
+    writeErr,
+    exit,
   });
 }