mandrel 1.69.0 → 1.71.0

package/lib/cli/update.js

@@ -48,13 +48,9 @@
  * 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.
+ * It is the **only** post-install execution path — tests stub the spawn
+ * boundary rather than swapping in an in-process implementation (No-Shim:
+ * `.agents/rules/git-conventions.md` § Contract Cutovers).
  *
  * ## No git mutation
  *
@@ -97,22 +93,14 @@
  *                             receives `(target, { installCmd })`
  *   - `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.
+ *                             and returns `{ ok, stdout, stderr }`. This is the
+ *                             sole post-install execution path. See § Re-exec of
+ *                             post-install phases.
  *   - `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)
+ *                             new binary path the post-install phases spawn from)
  *
  * Security (security-baseline § 5 — Data Leakage & Logging): logs only version
  * strings and step names. No tokens, credentials, or env
@@ -147,9 +135,7 @@ 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, runAgentsDrift } from './registry.js';
-import { runSync as defaultRunSync } from './sync.js';
+import { runAgentsDrift } from './registry.js';
 import { isStale } from './version-check.js';
 import { compareVersions } from './version-helpers.js';
 
@@ -632,25 +618,6 @@ function parseChangelogSections(raw) {
   return sections;
 }
 
-/**
- * Default doctor seam: run every check in the registry sequentially and
- * 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 }> }>}
- */
-async function defaultRunDoctor({ checks = registry } = {}) {
-  const results = [];
-  for (const check of checks) {
-    const r = await check.run();
-    results.push({ name: check.name, ok: Boolean(r.ok) });
-  }
-  return { ok: results.every((r) => r.ok), results };
-}
-
 /**
  * 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
@@ -735,6 +702,144 @@ const STEP_PLAN = [
   'surface changelog',
 ];
 
+/**
+ * The ordered post-install phase descriptors for a full upgrade. Each entry is
+ * a plain value (no I/O) describing one step the executor drives:
+ *
+ *   - `kind: 'npm-update'`  — bump the dependency via the `npmUpdate` seam.
+ *   - `kind: 'spawn'`       — spawn `phase`/`args` from the new binary; a
+ *                             non-zero exit is fatal and throws `failMessage`.
+ *   - `kind: 'doctor'`      — spawn `doctor` from the new binary; a non-zero
+ *                             exit is *soft* (maps to `action: 'doctor-failed'`
+ *                             + exit 1), so it carries no `failMessage`.
+ *
+ * `label` is the name pushed into the run's `stepsRun[]` (the external return
+ * contract). `migrate` is the only phase whose argv depends on the version
+ * range, so its descriptor is built per-plan in `planUpdate`.
+ *
+ * @param {string} current
+ * @param {string} target
+ * @returns {Array<{ kind: 'npm-update' | 'spawn' | 'doctor', label: string, phase?: string, args?: string[], failMessage?: string }>}
+ */
+function fullUpgradeSteps(current, target) {
+  return [
+    { kind: 'npm-update', label: 'npm-update' },
+    {
+      kind: 'spawn',
+      phase: 'sync',
+      args: [],
+      label: 'runSync',
+      failMessage:
+        'mandrel update: `mandrel sync` from new binary exited non-zero — ' +
+        'the .agents/ materialization may be incomplete. ' +
+        'Run `mandrel sync` manually to restore.',
+    },
+    {
+      kind: 'spawn',
+      phase: 'sync-commands',
+      args: [],
+      label: 'sync-commands',
+      failMessage:
+        '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.',
+    },
+    {
+      kind: 'spawn',
+      phase: 'migrate',
+      args: ['--from', current, '--to', target],
+      label: 'runMigrations',
+      failMessage:
+        '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.`,
+    },
+    { kind: 'doctor', phase: 'doctor', args: [], label: 'doctor' },
+  ];
+}
+
+/**
+ * The ordered phase descriptors for a drift-heal (version already current, but
+ * `.agents/` is stale). No npm-update, no migrations, no doctor — only the two
+ * sync phases re-materialize the payload from the already-installed binary.
+ *
+ * @returns {Array<{ kind: 'spawn', phase: string, args: string[], label: string, failMessage: string }>}
+ */
+function driftHealSteps() {
+  return [
+    {
+      kind: 'spawn',
+      phase: 'sync',
+      args: [],
+      label: 'runSync',
+      failMessage:
+        'mandrel update: `mandrel sync` from installed binary exited non-zero — ' +
+        'the .agents/ materialization may be incomplete. ' +
+        'Run `mandrel sync` manually to restore.',
+    },
+    {
+      kind: 'spawn',
+      phase: 'sync-commands',
+      args: [],
+      label: 'sync-commands',
+      failMessage:
+        '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.',
+    },
+  ];
+}
+
+/**
+ * Pure decision function for `mandrel update`: given the resolved version
+ * inputs and the two flags, decide which of the four actions to take and the
+ * ordered phase plan for that action. **No I/O** — no filesystem, child
+ * process, network, `write`, or `exit`. This isolates the scheduler-style
+ * branch-selection and step-sequencing logic (the surface under review in
+ * Story #4182 / audit::architecture) so it can be exercised as a table over
+ * plain inputs rather than by running the whole async orchestration with every
+ * seam stubbed.
+ *
+ * The four actions:
+ *
+ *   - `up-to-date` — version is current and no drift. True no-op; `steps: []`.
+ *   - `dry-run`    — `dryRun` is set. `steps: []` (nothing is executed); the
+ *                    `variant` distinguishes the drift-heal preview from the
+ *                    full-upgrade preview so the executor prints the right plan.
+ *   - `resynced`   — version is current but drift detected. Heal via the two
+ *                    sync phases (`driftHealSteps()`).
+ *   - `updated`    — a newer version is available. Full upgrade
+ *                    (`fullUpgradeSteps(current, target)`).
+ *
+ * @param {{ current: string, target: string, dryRun: boolean, hasDrift: boolean }} input
+ * @returns {{
+ *   action: 'up-to-date' | 'dry-run' | 'resynced' | 'updated',
+ *   steps: Array<{ kind: 'npm-update' | 'spawn' | 'doctor', label: string, phase?: string, args?: string[], failMessage?: string }>,
+ *   variant?: 'drift-heal' | 'full-upgrade',
+ * }}
+ */
+export function planUpdate({ current, target, dryRun, hasDrift }) {
+  const versionCurrent = compareVersions(target, current) <= 0;
+
+  if (versionCurrent) {
+    // Version is already newest. The only remaining question is drift.
+    if (!hasDrift) {
+      return { action: 'up-to-date', steps: [] };
+    }
+    if (dryRun) {
+      return { action: 'dry-run', steps: [], variant: 'drift-heal' };
+    }
+    return { action: 'resynced', steps: driftHealSteps() };
+  }
+
+  // A newer version is available — full upgrade (drift is irrelevant here; the
+  // post-upgrade doctor phase re-checks materialization).
+  if (dryRun) {
+    return { action: 'dry-run', steps: [], variant: 'full-upgrade' };
+  }
+  return { action: 'updated', steps: fullUpgradeSteps(current, target) };
+}
+
 /**
  * Extract the `--install-cmd "<cmd>"` value from the subcommand argv. Accepts
  * both the space form (`--install-cmd npm install …`, captured as the single
@@ -761,9 +866,125 @@ function parseInstallCmdFlag(argv) {
   return undefined;
 }
 
+/**
+ * Resolve the drift signal for the no-op short-circuit. Prefers the injected
+ * `checkDrift` seam (unit-test friendly); falls back to the production
+ * `runAgentsDrift` helper. Only consulted when the installed version is already
+ * the newest (Story #4065) — a real version bump skips drift entirely (the
+ * post-upgrade doctor phase re-checks materialization).
+ *
+ * @param {(() => boolean | Promise<boolean>) | undefined} checkDrift
+ * @returns {Promise<boolean>}
+ */
+async function resolveDrift(checkDrift) {
+  const driftProbe =
+    typeof checkDrift === 'function' ? checkDrift : () => !runAgentsDrift().ok;
+  return Boolean(await driftProbe());
+}
+
+/**
+ * Execute the ordered phase plan returned by `planUpdate` for the `updated` /
+ * `resynced` actions. This is the thin side-effecting shell: it owns the
+ * `npmUpdate` seam call, the `spawnPhase` re-exec boundary, the per-step
+ * `stepsRun` accounting, and the soft doctor-fail (`exit(1)` +
+ * `action: 'doctor-failed'`). The branch-selection logic that produced `steps`
+ * lives in the pure `planUpdate`.
+ *
+ * @param {{
+ *   steps: Array<{ kind: 'npm-update' | 'spawn' | 'doctor', label: string, phase?: string, args?: string[], failMessage?: string }>,
+ *   target: string,
+ *   installCmd: string | undefined,
+ *   npmUpdate: ((version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>) | undefined,
+ *   spawnPhase: ((phase: string, args: string[], opts: object) => { ok: boolean } | Promise<{ ok: boolean }>) | undefined,
+ *   surfaceChangelog: ((version: string) => unknown | Promise<unknown>) | undefined,
+ *   binPath: string,
+ *   projectRoot: string,
+ *   write: (s: string) => void,
+ *   writeErr: (s: string) => void,
+ *   exit: (code: number) => void,
+ * }} ctx
+ * @returns {Promise<{ stepsRun: string[], doctorOk: boolean }>}
+ */
+async function executePlan({
+  steps,
+  target,
+  installCmd,
+  npmUpdate,
+  spawnPhase,
+  surfaceChangelog,
+  binPath,
+  projectRoot,
+  write,
+  writeErr,
+  exit,
+}) {
+  const stepsRun = [];
+  let doctorOk = true;
+
+  for (const step of steps) {
+    if (step.kind === 'npm-update') {
+      // Bump the dependency. The lockfile change is left STAGED on disk; this
+      // module never commits.
+      if (typeof npmUpdate !== 'function') {
+        throw new Error(
+          'mandrel update: npmUpdate seam is required to bump the dependency',
+        );
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await npmUpdate(target, { installCmd });
+      stepsRun.push(step.label);
+      continue;
+    }
+
+    // Both 'spawn' and 'doctor' kinds run a post-install phase from the
+    // newly-installed binary (the Story #4034 re-exec boundary), so the new
+    // package's module code — not the old loaded module — executes.
+    // eslint-disable-next-line no-await-in-loop
+    const result = await spawnPhase(step.phase, step.args, {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    stepsRun.push(step.label);
+
+    if (step.kind === 'doctor') {
+      // Doctor failure is SOFT: record it, keep going to surface the changelog,
+      // then map to exit(1) + doctor-failed by the caller.
+      doctorOk = result.ok;
+    } else if (!result.ok) {
+      // sync / sync-commands / migrate failures are FATAL.
+      throw new Error(step.failMessage);
+    }
+  }
+
+  // Surface the target changelog (best-effort; optional seam). Runs even when
+  // doctor failed, so the operator still sees the changelog for the version
+  // that landed on disk.
+  if (typeof surfaceChangelog === 'function') {
+    await surfaceChangelog(target);
+  }
+
+  if (!doctorOk) {
+    writeErr(
+      `mandrel update: upgraded to v${target} but doctor reported failures.\n` +
+        '   → Run `mandrel doctor` for remedies.\n',
+    );
+    exit(1);
+  }
+
+  return { stepsRun, doctorOk };
+}
+
 /**
  * Run the `mandrel update` orchestration cycle.
  *
+ * The cycle is split into a pure decision (`planUpdate`) and a side-effecting
+ * shell (this function + `executePlan`). `runUpdate` resolves the inputs
+ * (current / target / drift) through the injectable seams, calls `planUpdate`
+ * to select the action and its ordered phase plan, then drives the plan through
+ * the `spawnPhase` / `write` / `exit` shell.
+ *
  * @param {{
  *   argv?: string[],
  *   currentVersion?: string | (() => string),
@@ -771,9 +992,6 @@ function parseInstallCmdFlag(argv) {
  *   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,
- *   runDoctor?: typeof defaultRunDoctor,
  *   surfaceChangelog?: (version: string) => unknown | Promise<unknown>,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
@@ -796,9 +1014,6 @@ export async function runUpdate({
   npmUpdate,
   checkDrift,
   spawnPhase,
-  runSync = defaultRunSync,
-  runMigrations = defaultRunMigrations,
-  runDoctor = defaultRunDoctor,
   surfaceChangelog,
   write = (s) => process.stdout.write(s),
   writeErr = (s) => process.stderr.write(s),
@@ -820,37 +1035,32 @@ export async function runUpdate({
   }
   const target = String(await resolveTargetVersion());
 
-  // --- No-op short-circuit --------------------------------------------------
-  // 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) {
-    // 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();
+  // Drift only matters when the installed version is already the newest. Probe
+  // it solely on that branch so a real version bump never calls the drift seam
+  // (Story #4065).
+  const hasDrift =
+    compareVersions(target, current) <= 0
+      ? await resolveDrift(checkDrift)
+      : false;
 
-    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,
-      };
-    }
+  const plan = planUpdate({ current, target, dryRun, hasDrift });
 
-    // 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) {
+  // --- up-to-date: true no-op ----------------------------------------------
+  if (plan.action === 'up-to-date') {
+    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,
+    };
+  }
+
+  // --- dry-run: print the plan, execute nothing -----------------------------
+  if (plan.action === 'dry-run') {
+    if (plan.variant === 'drift-heal') {
       write(
         `mandrel update — drift detected, sync heal planned (v${current} is already current)\n`,
       );
@@ -861,62 +1071,50 @@ export async function runUpdate({
         '  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,
-      };
+    } else {
+      write(`mandrel update — planned upgrade v${current} → v${target}\n`);
+      STEP_PLAN.forEach((step, i) => {
+        write(`  ${i + 1}. ${step}\n`);
+      });
+      write('Dry run: no files written, no dependency bumped.\n');
     }
+    return {
+      ok: true,
+      action: 'dry-run',
+      currentVersion: current,
+      targetVersion: target,
+      stepsRun: [],
+      dryRun: true,
+    };
+  }
+
+  // --- resynced / updated: execute the phase plan ---------------------------
+  const projectRoot = cwd();
+  const binPath = resolveNewBinPath(projectRoot);
 
+  if (plan.action === 'resynced') {
     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');
+  } else {
+    write(`Updating v${current} → v${target}…\n`);
+  }
 
-      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');
-    }
+  const { stepsRun, doctorOk } = await executePlan({
+    steps: plan.steps,
+    target,
+    installCmd,
+    npmUpdate,
+    spawnPhase,
+    surfaceChangelog,
+    binPath,
+    projectRoot,
+    write,
+    writeErr,
+    exit,
+  });
 
+  if (plan.action === 'resynced') {
     write(
       `✅  Healed .agents/ drift (v${current}). The materialized payload is now current.\n`,
     );
@@ -930,194 +1128,18 @@ export async function runUpdate({
     };
   }
 
-  // --- Dry run --------------------------------------------------------------
-  // Print the resolved target and the ordered step plan; invoke no seam and
-  // write nothing to disk.
-  if (dryRun) {
-    write(`mandrel update — planned upgrade v${current} → v${target}\n`);
-    STEP_PLAN.forEach((step, i) => {
-      write(`  ${i + 1}. ${step}\n`);
-    });
-    write('Dry run: no files written, no dependency bumped.\n');
+  // plan.action === 'updated'
+  if (!doctorOk) {
     return {
-      ok: true,
-      action: 'dry-run',
+      ok: false,
+      action: 'doctor-failed',
       currentVersion: current,
       targetVersion: target,
-      stepsRun: [],
-      dryRun: true,
+      stepsRun,
+      dryRun: false,
     };
   }
 
-  write(`Updating v${current} → v${target}…\n`);
-
-  const stepsRun = [];
-
-  // 1. npm update — bump the dependency. The lockfile change is left STAGED
-  //    on disk; this module never commits.
-  if (typeof npmUpdate !== 'function') {
-    throw new Error(
-      'mandrel update: npmUpdate seam is required to bump the dependency',
-    );
-  }
-  await npmUpdate(target, { installCmd });
-  stepsRun.push('npm-update');
-
-  // 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';
-
-  if (useReExec) {
-    // Re-exec path: post-install phases run from the new binary.
-    const projectRoot = cwd();
-    const binPath = resolveNewBinPath(projectRoot);
-
-    // 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');
-
-    // 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(
-      'migrate',
-      ['--from', current, '--to', target],
-      { binPath, cwd: projectRoot, write, writeErr },
-    );
-    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`);
   return {
     ok: true,
@@ -1180,9 +1202,6 @@ export async function runUpdate({
  *   changelogPath?: string,
  *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
- *   runSync?: typeof defaultRunSync,
- *   runMigrations?: typeof defaultRunMigrations,
- *   runDoctor?: typeof defaultRunDoctor,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
@@ -1201,9 +1220,6 @@ export default async function run(argv = [], deps = {}) {
     changelogPath,
     fetchChangelog,
     runUpdate: runUpdateImpl = runUpdate,
-    runSync,
-    runMigrations,
-    runDoctor,
     write = (s) => process.stdout.write(s),
     writeErr = (s) => process.stderr.write(s),
     exit = (code) => process.exit(code),
@@ -1212,30 +1228,17 @@ export default async function run(argv = [], 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.
+  // The production spawnPhase: spawn each post-install phase from
+  // node_modules/.bin/mandrel (the newly-installed binary). This is the sole
+  // post-install execution path (No-Shim — Story #4182 retired the in-process
+  // runSync/runMigrations/runDoctor seam set). 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,
@@ -1257,7 +1260,7 @@ export default async function run(argv = [], deps = {}) {
         runInstall: runInstall ?? runInstallCommand,
         fs,
       }),
-    ...phaseSeams,
+    spawnPhase: productionSpawnPhase,
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
         current,