mandrel 1.60.0 → 1.62.0

package/lib/cli/update.js

@@ -3,20 +3,20 @@
  * `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. drift-aware short-circuit — version check gates on installed version AND
+ *      materialized `.agents/` state (Story #4065). When already on newest AND
+ *      no drift: nothing to do (true no-op). When already on newest BUT drift
+ *      detected: skip npm-update/migrations, run sync + sync-commands to heal.
+ *   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,17 +25,17 @@
  *      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 newly-installed
+ *   4. runSync        — re-materialize ./.agents/ **from the newly-installed
  *      binary** so the materialized payload is always the target version's.
- *   6. runMigrations  — apply version-keyed steps for the crossed range,
+ *   5. runMigrations  — apply version-keyed steps for the crossed range,
  *      **from the newly-installed binary**.
- *   7. doctor         — run the check registry **from the newly-installed
+ *   6. doctor         — run the check registry **from the newly-installed
  *      binary** so `agents-drift` is never a false-green against stale payload.
- *   8. surface the changelog for the target version
+ *   7. surface the changelog for the target version
  *
  * ## Re-exec of post-install phases (Story #4034)
  *
- * Steps 5–7 execute as **child processes spawned from the newly-installed
+ * 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`
@@ -69,18 +69,6 @@
  * without invoking any effectful seam (no npm update, no sync, no migrations,
  * no doctor) and writing nothing.
  *
- * ## Major gate
- *
- * 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.
- *
  * ## Changelog surface
  *
  * `defaultSurfaceChangelog` prints the `docs/CHANGELOG.md` section(s) for the
@@ -100,6 +88,11 @@
  *   - `argv`                — subcommand args (after `mandrel update`)
  *   - `currentVersion`      — the installed `mandrel` version string
  *   - `resolveTargetVersion`— async, returns the newest published version
+ *   - `checkDrift`          — sync or async, returns `true` when `.agents/`
+ *                             differs from the installed payload. Used by the
+ *                             drift-aware no-op short-circuit (Story #4065).
+ *                             Defaults to `() => !runAgentsDrift().ok`, which
+ *                             reuses the same `agents-drift` doctor signal.
  *   - `npmUpdate`           — async, performs the dependency bump (no git);
  *                             receives `(target, { installCmd })`
  *   - `spawnPhase`          — async, spawns a post-install phase from the new
@@ -122,7 +115,7 @@
  *                             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).
  *
@@ -152,14 +145,13 @@ 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 { registry, runAgentsDrift } 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';
@@ -180,51 +172,6 @@ const GITHUB_RELEASES_URL = 'https://github.com/dsj1984/mandrel/releases';
 /** 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]}
- */
-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,
-  ];
-}
-
-/**
- * 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}
- */
-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;
-}
-
-/**
- * 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];
-}
-
 /**
  * Resolve the installed `mandrel` version from this package's own
  * `package.json`. The module lives at `<root>/lib/cli/update.js`, so the
@@ -255,12 +202,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
@@ -274,6 +224,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.
@@ -283,9 +234,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);
 }
 
@@ -352,28 +316,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 };
 }
 
 /**
@@ -749,10 +715,25 @@ export function defaultSpawnPhase(
 }
 
 /**
- * The ordered step names the orchestrator drives on a non-major bump. Shared
+ * 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
@@ -780,21 +761,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.
  *
@@ -803,6 +769,7 @@ function emitMajorRefusal(target, writeErr) {
  *   currentVersion?: string | (() => string),
  *   resolveTargetVersion?: () => (string | Promise<string>),
  *   npmUpdate?: (version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>,
+ *   checkDrift?: () => (boolean | Promise<boolean>),
  *   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,
@@ -815,10 +782,9 @@ function emitMajorRefusal(target, writeErr) {
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
- *   action: 'updated' | 'declined-major' | 'dry-run' | 'up-to-date' | 'doctor-failed',
+ *   action: 'updated' | 'resynced' | 'dry-run' | 'up-to-date' | 'doctor-failed',
  *   currentVersion: string,
  *   targetVersion: string | null,
- *   major: boolean,
  *   stepsRun: string[],
  *   dryRun: boolean,
  * }>}
@@ -828,6 +794,7 @@ export async function runUpdate({
   currentVersion,
   resolveTargetVersion,
   npmUpdate,
+  checkDrift,
   spawnPhase,
   runSync = defaultRunSync,
   runMigrations = defaultRunMigrations,
@@ -839,7 +806,6 @@ export async function runUpdate({
   cwd = () => process.cwd(),
 } = {}) {
   const dryRun = argv.includes('--dry-run');
-  const allowMajor = argv.includes('--major');
   const installCmd = parseInstallCmdFlag(argv);
 
   const current =
@@ -854,37 +820,113 @@ 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.
+  // Already on (or ahead of) the newest version: check whether .agents/ is
+  // actually materialized to the installed payload (agents-drift). When drift
+  // is present, fall through to a sync-only heal path even though the package
+  // version is unchanged. Only emit "Already up to date" when the version is
+  // current AND the payload matches (Story #4065).
   if (compareVersions(target, current) <= 0) {
-    write(`✅  Already up to date (v${current} is the newest version).\n`);
+    // Resolve the drift probe: prefer the injected checkDrift seam (unit-test
+    // friendly); fall back to the production runAgentsDrift helper.
+    const driftProbe =
+      typeof checkDrift === 'function'
+        ? checkDrift
+        : () => !runAgentsDrift().ok;
+    const hasDrift = await driftProbe();
+
+    if (!hasDrift) {
+      write(`✅  Already up to date (v${current} is the newest version).\n`);
+      return {
+        ok: true,
+        action: 'up-to-date',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun: [],
+        dryRun,
+      };
+    }
+
+    // Drift detected while version is already current — heal by re-syncing
+    // without bumping the package (no npm-update, no migrations needed since
+    // the installed version did not change).
+    if (dryRun) {
+      write(
+        `mandrel update — drift detected, sync heal planned (v${current} is already current)\n`,
+      );
+      write(
+        '  1. runSync        — re-materialize .agents/ from installed payload\n',
+      );
+      write(
+        '  2. sync-commands  — regenerate .claude/commands/ from .agents/workflows/\n',
+      );
+      write('Dry run: no files written.\n');
+      return {
+        ok: true,
+        action: 'dry-run',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun: [],
+        dryRun: true,
+      };
+    }
+
+    write(
+      `Healing .agents/ drift (v${current} is already current, but .agents/ is stale)…\n`,
+    );
+    const stepsRun = [];
+
+    const useReExec = typeof spawnPhase === 'function';
+
+    if (useReExec) {
+      const projectRoot = cwd();
+      const binPath = resolveNewBinPath(projectRoot);
+
+      const syncResult = await spawnPhase('sync', [], {
+        binPath,
+        cwd: projectRoot,
+        write,
+        writeErr,
+      });
+      if (!syncResult.ok) {
+        throw new Error(
+          `mandrel update: \`mandrel sync\` from installed binary exited non-zero — ` +
+            'the .agents/ materialization may be incomplete. ' +
+            'Run `mandrel sync` manually to restore.',
+        );
+      }
+      stepsRun.push('runSync');
+
+      const syncCommandsResult = await spawnPhase('sync-commands', [], {
+        binPath,
+        cwd: projectRoot,
+        write,
+        writeErr,
+      });
+      if (!syncCommandsResult.ok) {
+        throw new Error(
+          `mandrel update: \`mandrel sync-commands\` from installed 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');
+    } else {
+      // In-process backward-compat path.
+      runSync({ argv: [] });
+      stepsRun.push('runSync');
+    }
+
+    write(
+      `✅  Healed .agents/ drift (v${current}). The materialized payload is now current.\n`,
+    );
     return {
       ok: true,
-      action: 'up-to-date',
+      action: 'resynced',
       currentVersion: current,
       targetVersion: target,
-      major,
-      stepsRun: [],
-      dryRun,
+      stepsRun,
+      dryRun: false,
     };
   }
 
@@ -893,34 +935,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 = [];
 
@@ -970,7 +999,29 @@ export async function runUpdate({
     }
     stepsRun.push('runSync');
 
-    // 3. runMigrations from new bin — apply version-keyed steps for the
+    // 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');
+
+    // 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(
@@ -987,7 +1038,7 @@ export async function runUpdate({
     }
     stepsRun.push('runMigrations');
 
-    // 4. doctor from new bin — verify the resulting install. Running from the
+    // 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
@@ -1002,7 +1053,7 @@ export async function runUpdate({
     });
     stepsRun.push('doctor');
 
-    // 5. surface the target changelog (best-effort; optional seam).
+    // 6. surface the target changelog (best-effort; optional seam).
     if (typeof surfaceChangelog === 'function') {
       await surfaceChangelog(target);
     }
@@ -1018,7 +1069,6 @@ export async function runUpdate({
         action: 'doctor-failed',
         currentVersion: current,
         targetVersion: target,
-        major,
         stepsRun,
         dryRun: false,
       };
@@ -1034,6 +1084,9 @@ export async function runUpdate({
     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');
 
@@ -1059,7 +1112,6 @@ export async function runUpdate({
         action: 'doctor-failed',
         currentVersion: current,
         targetVersion: target,
-        major,
         stepsRun,
         dryRun: false,
       };
@@ -1072,7 +1124,6 @@ export async function runUpdate({
     action: 'updated',
     currentVersion: current,
     targetVersion: target,
-    major,
     stepsRun,
     dryRun: false,
   };
@@ -1082,20 +1133,21 @@ 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, 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 sync/migrate/doctor can never observe
- *     the old payload.
+ *     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. Reads from the packaged file first; falls back to
  *     a GitHub raw-content fetch via the injectable `fetchChangelog` seam when
@@ -1104,7 +1156,7 @@ export async function runUpdate({
  *
  * 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
@@ -1152,9 +1204,9 @@ export default async function run(argv = [], deps = {}) {
     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;
 
@@ -1170,46 +1222,53 @@ export default async function run(argv = [], deps = {}) {
       ...(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,
       }),
-    // In the production default export, always wire spawnPhase unless the
-    // caller injects the old-style in-process seams (runSync/runMigrations/
-    // runDoctor). When any old-style seam is present, fall back to in-process
-    // behavior to preserve the full backward-compat surface that the
-    // entrypoint test (update-entrypoint.test.js) relies on.
-    ...(runSync || runMigrations || runDoctor
-      ? {
-          ...(runSync ? { runSync } : {}),
-          ...(runMigrations ? { runMigrations } : {}),
-          ...(runDoctor ? { runDoctor } : {}),
-        }
-      : { spawnPhase: productionSpawnPhase }),
+    ...phaseSeams,
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
         current,
         fs,
         ...(changelogPath ? { changelogPath } : {}),
-        ...(fetchChangelog ? { fetchChangelog } : {}),
-        ...(write ? { write } : {}),
-        ...(writeErr ? { writeErr } : {}),
+        fetchChangelog: fetchChangelog ?? fetchChangelogFromGitHub,
+        write,
+        writeErr,
       }),
-    ...(write ? { write } : {}),
-    ...(writeErr ? { writeErr } : {}),
-    ...(exit ? { exit } : {}),
+    write,
+    writeErr,
+    exit,
   });
 }