mandrel 2.59.0 → 2.61.0

package/lib/cli/update.js

@@ -1,133 +1,12 @@
 // lib/cli/update.js
 /**
- * `mandrel update` subcommand — the auto-update orchestrator (f-update-command,
- * Story #3503, Epic #3437 — Auto-Update & Version Lifecycle).
- *
- * 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)
- *
- *   1. resolve target version (newest published) and the current version
- *   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
- *      `npm install …`. An explicit `--install-cmd "<pm> <args>"` overrides
- *      detection; a `{target}` placeholder in the override is substituted with
- *      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).
- *   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
- * bin script** (`node <cwd>/node_modules/mandrel/bin/mandrel.js`; Story #4613
- * resolves the script layout-agnostically rather than via the `.bin` shim)
- * 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.
- * 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
- *
- * The npm dependency bump rewrites `package.json` / `package-lock.json` in the
- * working tree but the orchestrator performs **no** `git add` / `git commit`:
- * the lockfile bump is left staged-on-disk for the operator to review and
- * commit. This module never shells out to git.
- *
- * ## `--dry-run`
- *
- * Prints the resolved target version and the ordered step plan, then returns
- * without invoking any effectful seam (no npm update, no sync, no migrations,
- * no doctor) and writing nothing.
- *
- * ## 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).
- *
- * 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)
- *
- *   - `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
- *                             binary; receives `(phase, args, { binPath, cwd })`
- *                             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 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
- * values are read or logged; no shell-string interpolation occurs here (the
- * npm bump is delegated to the injected `npmUpdate` seam, which owns transport).
- *
- * ## Windows spawn (CVE-2024-27980)
- *
- * Both child-process boundaries — the `npm view` registry probe and the
- * install — route through helpers that pass `shell: process.platform ===
- * 'win32'`. On Windows `npm`/`pnpm`/`yarn` resolve to `.cmd` shims, and
- * Node 18.20+/20.12+/22+/24 refuses to spawn `.cmd`/`.bat` with `shell:false`
- * (the CVE-2024-27980 hardening), throwing `spawnSync npm ENOENT`. The win32
- * shell flag is the documented fix. It is injection-safe because every argv
- * here is a **fixed vector**: the probe argv is the constant package name, and
- * 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) does **not** use the win32 shell flag:
- * it spawns `process.execPath` (node) against the resolved `bin/mandrel.js`
- * script (Story #4613), so it never touches a `.cmd` shim and needs no
- * shell on any platform. The per-phase argv vector is a constant fixed list
- * (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`, `['doctor']`) with
- * no operator-supplied data.
+ * `mandrel update`: install the newest published version, then re-materialize
+ * `.agents/`, run migrations and doctor from the NEW binary (Node cannot
+ * hot-swap loaded modules, so in-process phases would materialize the old
+ * payload), and surface the changelog. Already-newest with `.agents/` drift
+ * runs only the sync phases. Never mutates git: it reports the real index state.
+ * Windows: `npm`/`pnpm`/`yarn` are `.cmd` shims that need `shell: true` under
+ * CVE-2024-27980; every argv here is a fixed vector, so that stays safe.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -146,38 +25,18 @@ import {
   resolveConsumerPinVersion,
 } from './version-helpers.js';
 
-/** The published package whose newest version `mandrel update` advances to. */
 const PACKAGE_NAME = 'mandrel';
 
-/**
- * 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`.
- */
 const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/dsj1984/mandrel/';
 
-/**
- * Human-readable GitHub Releases page — surfaced in the actionable fallback
- * message when neither the packaged file nor the GitHub fetch succeeds.
- */
 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';
 
 /**
- * Resolve the installed `mandrel` version from this package's own
- * `package.json`. The module lives at `<root>/lib/cli/update.js`, so the
- * manifest is two directories up.
- *
- * Pre-Story-#4525 this was the update decision's `current` — the exact
- * self-referential confusion #4525 filed: "the version of the mandrel that
- * is executing" is tautologically `>= target` whenever the installed
- * package is newest, which made the `npm-update` step unreachable whenever
- * a consumer's declared pin had fallen behind what happened to be resolved
- * in `node_modules`. It survives here only as the last-resort fallback
- * inside {@link resolveCurrentVersionForUpdate}, for the case where even
- * `node_modules` resolution from the consumer root fails.
+ * The version of the EXECUTING package — last-resort fallback only: as the
+ * update decision's `current` it is tautologically newest and would hide a
+ * lagging consumer pin.
  *
  * @param {typeof nodeFs} [fs]
  * @returns {string}
@@ -190,27 +49,14 @@ function defaultCurrentVersion(fs = nodeFs) {
 }
 
 /**
- * Resolve the "current" version for the `mandrel update` decision
- * (Story #4525 / #4530): the consumer's declared `mandrel` dependency pin
- * when it resolves to a plain semver, falling back — in order — to the
- * version actually resolvable in the consumer's `node_modules` (anchored at
- * `consumerRoot` via the same resolution `mandrel sync` uses, unlike the
- * pre-#4525 self-referential `defaultCurrentVersion`), and finally to
- * `defaultCurrentVersion` itself when neither resolves (a corrupted or
- * highly unusual install — keeps `mandrel update` from throwing outright
- * rather than silently misreporting "already current").
- *
- * The declared pin is preferred because it is exactly what the `npm-update`
- * step moves: a consumer whose `package.json` pin lags an inflated
- * `node_modules` resolution (e.g. an out-of-band symlink or manual
- * `npm install mandrel@latest --no-save`) must still see `planUpdate`
- * choose `updated`, not `resynced` — the bug #4525 reported.
+ * The update decision's `current`: the consumer's declared pin (it is what
+ * `npm-update` moves, so a pin lagging an inflated `node_modules` still
+ * updates), else the consumer's resolved `node_modules` version, else the
+ * executing package's own.
  *
  * @param {string} consumerRoot
  * @param {typeof nodeFs} [fs]
- * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts] - test
- *   seam for the `node_modules` resolution tier; defaults to the real
- *   `defaultResolvePackageRoot` from `sync.js`.
+ * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts]
  * @returns {string}
  */
 export function resolveCurrentVersionForUpdate(
@@ -231,42 +77,15 @@ export function resolveCurrentVersionForUpdate(
   }
 }
 
-/**
- * Resolve the project root — the directory two levels up from this module
- * (`<root>/lib/cli/update.js`). Mirrors `lib/cli/registry.js#resolveProjectRoot`.
- *
- * @returns {string}
- */
+/** @returns {string} */
 function resolveProjectRoot() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   return path.resolve(here, '..', '..');
 }
 
 /**
- * Default `resolveTargetVersion` seam: determine the newest published
- * `mandrel` version via the daily freshness cache (`version-check.js`).
- *
- * When `bypassCache` is `true` (the default for an explicit `mandrel update`
- * call — Story #4046 A1b), `isStale` is asked to skip its freshness read via
- * `forceRefresh`, so any existing cache is ignored and exactly one network
- * probe is issued. The cache is still written so the post-update
- * `version-current` advisory has a fresh baseline.
- *
- * The bypass deliberately does **not** shift `now`: the same clock is stamped
- * into the refreshed `checkedAt`, so a shifted clock would persist a
- * ~48h-future timestamp and defeat the 24h window for every later passive
- * check until real time caught up (Story #4878).
- *
- * 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
- * Windows the spawn sets `shell: true` so the `npm.cmd` shim resolves under the
- * CVE-2024-27980 hardening (mirrors `lib/install-cmd-parser.js`); the fixed
- * argv carries no injection risk even with the shell flag set
- * (security-baseline § Output & Rendering).
+ * Newest published version via the daily freshness cache. `bypassCache` forces
+ * one probe but still writes the cache.
  *
  * @param {{
  *   cachePath?: string,
@@ -286,9 +105,8 @@ async function defaultResolveTargetVersion({
   bypassCache = false,
   log = () => {},
 } = {}) {
-  // Bypass the cache by telling isStale to skip its freshness read — never by
-  // shifting `now`, which is also the clock persisted as `checkedAt`
-  // (Story #4046 A1b forcing the probe; Story #4878 keeping the stamp honest).
+  // Bypass via forceRefresh, never by shifting `now`: `now` is persisted as
+  // `checkedAt`, and a shifted stamp would defeat the 24h window.
   const result = await isStale({
     cachePath,
     now,
@@ -301,15 +119,10 @@ async function defaultResolveTargetVersion({
 }
 
 /**
- * Default network `runner` for the freshness probe: shells
- * `npm view mandrel version` synchronously and returns the trimmed
- * stdout. Fixed argv (the package name is a constant), and `shell:true` only on
- * Windows so the `npm.cmd` shim resolves under CVE-2024-27980 — the fixed
- * vector keeps it injection-safe with or without the shell flag.
+ * `npm view mandrel version`, trimmed.
  *
- * @param {{ spawnSync?: typeof spawnSync }} [deps] — test seam for the spawn
- *   boundary; defaults to the real `node:child_process` spawnSync.
- * @returns {string} The newest published version string.
+ * @param {{ spawnSync?: typeof spawnSync }} [deps]
+ * @returns {string}
  */
 export function defaultVersionRunner({ spawnSync: spawn = spawnSync } = {}) {
   const r = spawn('npm', ['view', PACKAGE_NAME, 'version'], {
@@ -337,9 +150,7 @@ export function defaultVersionRunner({ spawnSync: spawn = spawnSync } = {}) {
 }
 
 /**
- * Map a detected package manager to the command that re-runs a full install.
- * Surfaced in the repair hint when an install fails so the operator can restore
- * `node_modules` to a consistent state (Story #3575 AC-4).
+ * The full-install command named in the failed-install repair hint.
  *
  * @param {'pnpm' | 'yarn' | 'npm'} packageManager
  * @returns {string}
@@ -351,29 +162,30 @@ function repairInstallCommand(packageManager) {
 }
 
 /**
- * Detect the project's package manager by probing for a lockfile in `cwd`.
- * Precedence mirrors the ecosystem norm: a `pnpm-lock.yaml` wins over a
- * `yarn.lock`, which wins over the npm default. `workspaceRoot` is true only
- * for pnpm when a `pnpm-workspace.yaml` sits alongside the lockfile — the
- * signal that `pnpm add` must carry `-w` to target the workspace-root manifest.
- *
- * Running the wrong package manager (e.g. `npm install` in a pnpm workspace) is
- * the root cause this resolves (Story #3575): npm chokes on the pnpm-managed
- * tree, exits non-zero, and can flip `node_modules` to a stale store entry.
- * Detecting the lockfile keeps the bump on the operator's real package manager
- * so the change lands in the matching lockfile.
+ * The lockfile-detected package manager, so the bump runs under the tool that
+ * owns the tree (npm in a pnpm workspace fails and can corrupt `node_modules`).
+ * `workspaceRoot` means `pnpm add` needs `-w`. `bun` coerces to `npm`: the
+ * install builder has no bun command.
  *
- * 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 {string} [cwd]
  * @param {typeof nodeFs} [fs]
  * @returns {{ packageManager: 'pnpm' | 'yarn' | 'npm', workspaceRoot: boolean }}
  */
 export function detectPackageManager(cwd = process.cwd(), fs = nodeFs) {
+  const result = probePackageManager(cwd, fs);
+  const packageManager =
+    result.packageManager === 'bun' ? 'npm' : result.packageManager;
+  return { packageManager, workspaceRoot: result.workspaceRoot };
+}
+
+/**
+ * The uncoerced probe; the staging report must name bun's real lockfile.
+ *
+ * @param {string} cwd
+ * @param {typeof nodeFs} [fs]
+ * @returns {{ packageManager: 'pnpm'|'yarn'|'bun'|'npm', workspaceRoot: boolean }}
+ */
+function probePackageManager(cwd, fs = nodeFs) {
   const exists = (p) => {
     try {
       return fs.existsSync(p);
@@ -381,33 +193,15 @@ export function detectPackageManager(cwd = process.cwd(), fs = nodeFs) {
       return 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 };
+  return detectPackageManagerWithWorkspace(cwd, exists);
 }
 
 /**
- * Resolve the install command string `defaultNpmUpdate` runs.
- *
- * With no override the command is built from the detected package manager:
- *   - `pnpm` ⇒ `pnpm add -D mandrel@<target>` (plus ` -w` at a pnpm
- *     workspace root)
- *   - `yarn` ⇒ `yarn add -D mandrel@<target>`
- *   - `npm`  ⇒ `npm install mandrel@<target>` (the unchanged default)
- *
- * An explicit `--install-cmd` override is used verbatim, except that a
- * `{target}` placeholder is substituted with the resolved semver so an override
- * can still consume the auto-probed newest version (Story #3575 AC-3).
- *
- * This function is pure: package-manager detection happens in
- * `detectPackageManager` (the only filesystem seam) and is passed in as
- * `detected`, keeping the command-string assembly trivially unit-testable.
+ * The install command. An `--install-cmd` override is used verbatim except
+ * that `{target}` is replaced with the resolved semver.
  *
- * @param {string} target - The resolved semver to install.
- * @param {string} [override] - Operator-supplied `--install-cmd` value.
+ * @param {string} target
+ * @param {string} [override]
  * @param {{
  *   packageManager?: 'pnpm' | 'yarn' | 'npm',
  *   workspaceRoot?: boolean,
@@ -434,27 +228,221 @@ export function resolveInstallCmd(
   return `npm install ${PACKAGE_NAME}@${target}`;
 }
 
+const LOCKFILE_BY_PACKAGE_MANAGER = {
+  pnpm: 'pnpm-lock.yaml',
+  yarn: 'yarn.lock',
+  bun: 'bun.lockb',
+  npm: 'package-lock.json',
+};
+
+const MANIFEST_FILENAME = 'package.json';
+
+const AGENTS_DIR = '.agents';
+
+/**
+ * @param {string} cwd
+ * @param {typeof nodeFs} [fs]
+ * @returns {string}
+ */
+export function defaultDetectLockfile(cwd, fs = nodeFs) {
+  const { packageManager } = probePackageManager(cwd, fs);
+  return LOCKFILE_BY_PACKAGE_MANAGER[packageManager] ?? 'package-lock.json';
+}
+
+const NEUTRAL_STAGING_LINE =
+  'Review the working tree and commit the bump (git not available to report staging state).';
+
+const DEGRADED_GIT_STATE = Object.freeze({
+  ok: false,
+  stagedManifest: false,
+  stagedLockfile: false,
+  stagedPayload: false,
+  tracksAgents: false,
+});
+
+const spawnOk = (result) =>
+  Boolean(result) && !result.error && result.status === 0;
+
+/**
+ * The path a porcelain v1 record reports as staged, else `null`. Staged means
+ * index differs from HEAD AND the worktree agrees (`Y` blank), so a pair staged
+ * before the install and rewritten by it (`MM`) is not staged. Renames yield
+ * the new path; porcelain quoting is stripped.
+ *
+ * @param {string} record
+ * @returns {string | null}
+ */
+function stagedPathFromPorcelain(record) {
+  if (record.length < 4 || record[1] !== ' ') return null;
+  if (record[0] === ' ' || record[0] === '?') return null;
+  const raw = record.slice(3).trim();
+  const arrow = raw.lastIndexOf(' -> ');
+  const pathPart = arrow === -1 ? raw : raw.slice(arrow + 4);
+  const path =
+    pathPart.startsWith('"') && pathPart.endsWith('"')
+      ? pathPart.slice(1, -1)
+      : pathPart;
+  return path.length > 0 ? path : null;
+}
+
+/**
+ * The probe-state slot a staged path fills. Payload is tested first (a
+ * `package.json` inside `.agents/` is payload). The manifest/lockfile tests
+ * accept a leading prefix because porcelain paths are repo-root-relative;
+ * that is safe only because the caller's pathspec anchors the query at `cwd`.
+ *
+ * @param {string} path
+ * @param {string} lockfile
+ * @returns {'stagedPayload' | 'stagedManifest' | 'stagedLockfile' | null}
+ */
+function stagedSlotFor(path, lockfile) {
+  if (path === AGENTS_DIR || /(^|\/)\.agents\//.test(path))
+    return 'stagedPayload';
+  const isRootFile = (name) => path === name || path.endsWith(`/${name}`);
+  if (isRootFile(MANIFEST_FILENAME)) return 'stagedManifest';
+  return isRootFile(lockfile) ? 'stagedLockfile' : null;
+}
+
 /**
- * Default `npmUpdate` seam: install the resolved target version. The install
- * rewrites `package.json` / the lockfile on disk (left staged for the
- * operator); this performs no git mutation.
+ * Read-only index probe: a `cwd`-anchored `git status --porcelain` over the
+ * manifest, lockfile and `.agents`, plus `git ls-files .agents` (is the
+ * payload tracked?). Never throws; any failure degrades to `{ ok: false }`.
  *
- * The package manager is auto-detected from `cwd`'s lockfile (Story #3575) so
- * the bump lands in the operator's real lockfile rather than running
- * `npm install` against a pnpm/yarn-managed tree. The install routes through
- * the shared `runInstallCommand` helper from `lib/install-cmd-parser.js`, which
- * tokenizes the command and spawns with `shell: process.platform === 'win32'`
- * so the Windows `.cmd` shim resolves under CVE-2024-27980 — the win32 shell
- * handling and tokenization are reused, not re-implemented here. The resolved
- * argv is a fixed vector; an `--install-cmd` override is tokenized and escaped
- * per-arg by the parser even when the win32 shell flag is required.
+ * @param {{
+ *   cwd?: string,
+ *   lockfile?: string,
+ *   spawnSync?: typeof spawnSync,
+ * }} [opts]
+ * @returns {{
+ *   ok: boolean,
+ *   stagedManifest: boolean,
+ *   stagedLockfile: boolean,
+ *   stagedPayload: boolean,
+ *   tracksAgents: boolean,
+ * }}
+ */
+export function defaultGitStatus({
+  cwd = process.cwd(),
+  lockfile = LOCKFILE_BY_PACKAGE_MANAGER.npm,
+  spawnSync: spawn = spawnSync,
+} = {}) {
+  const run = (args) => spawn('git', args, { cwd, encoding: 'utf8' });
+  try {
+    const status = run([
+      'status',
+      '--porcelain',
+      '--',
+      MANIFEST_FILENAME,
+      lockfile,
+      AGENTS_DIR,
+    ]);
+    if (!spawnOk(status)) return DEGRADED_GIT_STATE;
+    const agents = run(['ls-files', AGENTS_DIR]);
+    const state = {
+      ...DEGRADED_GIT_STATE,
+      ok: true,
+      tracksAgents: spawnOk(agents) && String(agents.stdout).trim().length > 0,
+    };
+    for (const record of String(status.stdout).split('\n')) {
+      const path = stagedPathFromPorcelain(record);
+      const slot = path && stagedSlotFor(path, lockfile);
+      if (slot) state[slot] = true;
+    }
+    return state;
+  } catch {
+    return DEGRADED_GIT_STATE;
+  }
+}
+
+/**
+ * The staging line a successful run closes with. `bump` reports the manifest +
+ * lockfile pair, and a not-staged hint also names a tracked `.agents/` (else
+ * that diff is silently dropped). `payload` (drift heal) reports only
+ * `.agents/`, or `''` when it is untracked.
  *
- * On any install failure the thrown error names the detected package manager's
- * own `install` command so the operator can restore `node_modules` to a
- * consistent state — `mandrel update` never silently leaves a half-mutated
- * tree (Story #3575 AC-4).
+ * @param {{
+ *   ok?: boolean,
+ *   stagedManifest?: boolean,
+ *   stagedLockfile?: boolean,
+ *   stagedPayload?: boolean,
+ *   tracksAgents?: boolean,
+ * }} gitState
+ * @param {string} lockfile
+ * @param {{ scope?: 'bump' | 'payload' }} [opts]
+ * @returns {string}
+ */
+export function formatStagingReport(
+  gitState,
+  lockfile,
+  { scope = 'bump' } = {},
+) {
+  const {
+    ok = false,
+    stagedManifest = false,
+    stagedLockfile = false,
+    stagedPayload = false,
+    tracksAgents = false,
+  } = gitState ?? {};
+
+  if (!ok) return NEUTRAL_STAGING_LINE;
+
+  if (scope === 'payload') {
+    if (!tracksAgents) return '';
+    return stagedPayload
+      ? `The re-materialized ${AGENTS_DIR}/ payload is staged for review.`
+      : `The re-materialized ${AGENTS_DIR}/ payload is NOT staged. Review and stage it: git add ${AGENTS_DIR}/`;
+  }
+
+  if (stagedManifest && stagedLockfile) {
+    return `The dependency bump is staged for review (${MANIFEST_FILENAME}, ${lockfile}).`;
+  }
+
+  const targets = [MANIFEST_FILENAME, lockfile];
+  let note = '';
+  if (tracksAgents) {
+    targets.push(`${AGENTS_DIR}/`);
+    note = ` ${AGENTS_DIR}/ is tracked here, so stage the re-materialized payload too.`;
+  }
+  return `The dependency bump is NOT staged.${note} Review and stage it: git add ${targets.join(' ')}`;
+}
+
+/**
+ * The staging line, degrading any seam failure to the neutral line so a
+ * courtesy report never crashes a completed update.
  *
- * @param {string} target - The version to install.
+ * @param {{
+ *   gitStatus: (opts: { cwd: string, lockfile: string }) => object,
+ *   detectLockfile: (cwd: string) => string,
+ *   projectRoot: string,
+ *   scope?: 'bump' | 'payload',
+ * }} deps
+ * @returns {string}
+ */
+function resolveStagingReport({
+  gitStatus,
+  detectLockfile,
+  projectRoot,
+  scope = 'bump',
+}) {
+  try {
+    const lockfile = detectLockfile(projectRoot);
+    return formatStagingReport(
+      gitStatus({ cwd: projectRoot, lockfile }),
+      lockfile,
+      { scope },
+    );
+  } catch {
+    return NEUTRAL_STAGING_LINE;
+  }
+}
+
+/**
+ * Install `target` with the detected package manager (no git mutation). The
+ * shared `runInstallCommand` tokenizes and escapes per-arg under the win32
+ * shell. A failure names the repair install so `node_modules` is never left
+ * silently half-mutated.
+ *
+ * @param {string} target
  * @param {{
  *   installCmd?: string,
  *   runInstall?: typeof runInstallCommand,
@@ -494,30 +482,16 @@ 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.
+ * `docs/CHANGELOG.md` from GitHub raw, for installs whose package lacks it.
+ * Tags are `mandrel-vX.Y.Z` from 1.44.0 and bare `vX.Y.Z` before, so both
+ * are tried.
  *
- * 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 {string} version
  * @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.
+ * @returns {Promise<string>}
+ * @throws {Error} When every tag form is non-2xx or the request errors.
  */
 export async function fetchChangelogFromGitHub(
   version,
@@ -560,25 +534,10 @@ export async function fetchChangelogFromGitHub(
 }
 
 /**
- * Default `surfaceChangelog` seam: print the `docs/CHANGELOG.md` section(s)
- * covering the applied version range `(current, target]`. The changelog is
- * authored by release-please with `## [<version>](…)` section headers; this
- * prints every section whose version is newer than `current` and no newer than
- * `target`.
- *
- * 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".
+ * Print the changelog sections in `(current, target]` — packaged file first,
+ * then GitHub, then a Releases link. Best-effort: warns, never throws.
  *
- * 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 {string} target
  * @param {{
  *   current?: string,
  *   changelogPath?: string,
@@ -602,19 +561,16 @@ async function defaultSurfaceChangelog(
 ) {
   let raw;
 
-  // 1. Try the packaged file (present in installs since Story #4035).
   try {
     raw = fs.readFileSync(changelogPath, 'utf8');
   } catch {
-    // File absent — fall through to GitHub fetch.
+    // Absent: fall through to the 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`,
@@ -645,9 +601,8 @@ async function defaultSurfaceChangelog(
 }
 
 /**
- * Split a release-please `CHANGELOG.md` into `{ version, body }` sections keyed
- * by the `## [<version>]…` headers. Each `body` includes the header line and
- * everything up to (but not including) the next version header.
+ * Split a release-please changelog on `## [<version>]` headers; each body
+ * includes its header line.
  *
  * @param {string} raw
  * @returns {Array<{ version: string, body: string }>}
@@ -680,32 +635,13 @@ function parseChangelogSections(raw) {
 }
 
 /**
- * Resolve the newly-installed `mandrel` bin **script**
- * (`<packageRoot>/bin/mandrel.js`) from the consumer project root. This is the
- * target for the post-install phase re-exec (Story #4034), spawned via
- * `process.execPath` (node) rather than executed directly — see
- * {@link defaultSpawnPhase}.
+ * The consumer's installed `bin/mandrel.js`, NOT the `.bin` shim: the script
+ * ships non-executable and pnpm symlinks the shim straight at it, so spawning
+ * the shim fails with EACCES. Node runs the script directly instead.
  *
- * It deliberately does **not** return the `node_modules/.bin/mandrel` shim.
- * That shim only works because npm chmods the bin target `+x` at install time:
- * `bin/mandrel.js` ships non-executable in the published tarball, and pnpm
- * symlinks `.bin/mandrel` straight at it, so spawning the shim directly fails
- * with `EACCES` under pnpm (Story #4613). Spawning node against the resolved
- * `.js` script removes the dependency on the exec bit, the shebang, and the
- * Windows `.cmd` shim entirely.
- *
- * Resolution reuses the same consumer-anchored resolver
- * (`defaultResolvePackageRoot`) that {@link resolveCurrentVersionForUpdate}
- * uses, so it points at the consumer's install rather than a copy hoisted next
- * to this CLI module. The `mandrel` package directory is version-invariant
- * (`node_modules/mandrel/`), so resolving it before the in-place `npm-update`
- * step still yields the directory whose `bin/mandrel.js` the install overwrites.
- *
- * @param {string} projectRoot - Absolute path to the consumer project.
- * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts] - test
- *   seam for the `node_modules` resolution; defaults to the real
- *   `defaultResolvePackageRoot` from `sync.js`.
- * @returns {string} Absolute path to the new bin script.
+ * @param {string} projectRoot
+ * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts]
+ * @returns {string}
  */
 export function resolveNewBinScriptPath(
   projectRoot,
@@ -716,33 +652,19 @@ export function resolveNewBinScriptPath(
 }
 
 /**
- * Default `spawnPhase` seam (Story #4034): spawn a post-install phase from the
- * newly-installed `mandrel` bin script 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 child is spawned as `process.execPath <binScript> <phase> …` — node run
- * against the resolved `bin/mandrel.js` (see {@link resolveNewBinScriptPath}).
- * Spawning node against a plain `.js` file removes any dependency on the bin's
- * exec bit, its shebang, or a Windows `.cmd` shim, so **no** `shell` flag is
- * needed on any platform (this is the pnpm/layout-agnostic fix, Story #4613,
- * that retired the former win32-only `shell: true` branch). The argv vector is
- * a fixed constant list per phase — no operator-supplied data enters it
- * (security-baseline § Output & Rendering).
+ * Run one post-install phase as `node <binScript> <phase> …` so the new
+ * package's code executes; no shell is needed on any platform. Throws only on
+ * a spawn error.
  *
- * 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 {string} phase
+ * @param {string[]} args
  * @param {{
  *   binPath: string,
  *   cwd: string,
  *   write: (s: string) => void,
  *   writeErr: (s: string) => void,
  *   spawnFn?: typeof spawnSync,
- * }} opts - `binPath` is the resolved bin **script** path (not the
- *   `node_modules/.bin` shim); it becomes node's first argv entry.
+ * }} opts
  * @returns {{ ok: boolean, stdout: string, stderr: string }}
  */
 export function defaultSpawnPhase(
@@ -768,19 +690,7 @@ export function defaultSpawnPhase(
   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; sync-agents added by Story #4528/#4530):
- *   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. sync-agents    — regenerate .claude/agents/ from the new payload
- *   5. runMigrations  — apply version-keyed migrations
- *   6. doctor         — validate the post-upgrade state
- *   7. surface changelog — print the changelog (always last, best-effort)
- */
+/** The `--dry-run` printout of the full-upgrade step order. */
 const STEP_PLAN = [
   'npm-update',
   'runSync',
@@ -792,19 +702,9 @@ const STEP_PLAN = [
 ];
 
 /**
- * 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`.
+ * Full-upgrade phases. A `spawn` non-zero exit is fatal (throws
+ * `failMessage`); a `doctor` failure is soft (`doctor-failed`, exit 1).
+ * `label` is what `stepsRun[]` reports.
  *
  * @param {string} current
  * @param {string} target
@@ -834,10 +734,7 @@ function fullUpgradeSteps(current, target) {
         'Run `npm run sync:commands` manually to restore.',
     },
     {
-      // Story #4528/#4530: the CLI update path previously never projected the
-      // role-agent tree at all — only the bootstrap path did. Added alongside
-      // sync-commands so `.claude/agents/` materializes here too, which is
-      // what makes the tightened `agents-in-sync` doctor check satisfiable.
+      // Required for the `agents-in-sync` doctor check to be satisfiable.
       kind: 'spawn',
       phase: 'sync-agents',
       args: [],
@@ -862,10 +759,7 @@ function fullUpgradeSteps(current, target) {
 }
 
 /**
- * The ordered phase descriptors for a drift-heal (version already current, but
- * `.agents/` is stale). No npm-update, no migrations, no doctor — only the
- * three sync phases re-materialize the payload from the already-installed
- * binary.
+ * Drift-heal phases: the sync phases only, from the installed binary.
  *
  * @returns {Array<{ kind: 'spawn', phase: string, args: string[], label: string, failMessage: string }>}
  */
@@ -892,7 +786,6 @@ function driftHealSteps() {
         'Run `npm run sync:commands` manually to restore.',
     },
     {
-      // Story #4528/#4530: see the matching entry in fullUpgradeSteps().
       kind: 'spawn',
       phase: 'sync-agents',
       args: [],
@@ -906,25 +799,7 @@ function driftHealSteps() {
 }
 
 /**
- * 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)`).
+ * Pure (no I/O) choice of action and phase plan.
  *
  * @param {{ current: string, target: string, dryRun: boolean, hasDrift: boolean }} input
  * @returns {{
@@ -937,7 +812,6 @@ 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: [] };
     }
@@ -947,8 +821,7 @@ export function planUpdate({ current, target, dryRun, hasDrift }) {
     return { action: 'resynced', steps: driftHealSteps() };
   }
 
-  // A newer version is available — full upgrade (drift is irrelevant here; the
-  // post-upgrade doctor phase re-checks materialization).
+  // Drift is irrelevant here: the post-upgrade doctor re-checks it.
   if (dryRun) {
     return { action: 'dry-run', steps: [], variant: 'full-upgrade' };
   }
@@ -956,14 +829,8 @@ export function planUpdate({ current, target, dryRun, hasDrift }) {
 }
 
 /**
- * Extract the `--install-cmd "<cmd>"` value from the subcommand argv. Accepts
- * both the space form (`--install-cmd npm install …`, captured as the single
- * following token group) and the `=` form (`--install-cmd="<cmd>"`). Returns
- * `undefined` when the flag is absent so the default package manager is used.
- *
- * The argv tokenizer hands us a pre-split array; with the space form the shell
- * has already collapsed a quoted value into one element, so the immediate next
- * token is the full command string.
+ * `--install-cmd <cmd>` or `--install-cmd=<cmd>`; the shell has already joined
+ * a quoted value into one token.
  *
  * @param {string[]} argv
  * @returns {string | undefined}
@@ -982,12 +849,6 @@ function parseInstallCmdFlag(argv) {
 }
 
 /**
- * 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>}
  */
@@ -998,12 +859,8 @@ async function resolveDrift(checkDrift) {
 }
 
 /**
- * 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`.
+ * Drive `planUpdate`'s steps. A doctor failure still surfaces the changelog,
+ * then exits 1.
  *
  * @param {{
  *   steps: Array<{ kind: 'npm-update' | 'spawn' | 'doctor', label: string, phase?: string, args?: string[], failMessage?: string }>,
@@ -1036,11 +893,8 @@ async function executePlan({
   const stepsRun = [];
   let doctorOk = true;
 
-  // Resolve the new bin script lazily and once, on the first spawn phase.
-  // Deferring it past the `npm-update` step means (a) a missing `npmUpdate`
-  // seam surfaces its own clear error first, and (b) resolution reflects the
-  // just-installed package. The `mandrel` package directory is version-stable,
-  // so resolving after the in-place bump yields the same directory either way.
+  // Resolved lazily after `npm-update`, so a missing npmUpdate seam reports
+  // its own error first.
   let binPath;
   const binScript = () => {
     if (binPath === undefined) binPath = resolveBinScript(projectRoot);
@@ -1049,8 +903,6 @@ async function executePlan({
 
   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',
@@ -1062,9 +914,6 @@ async function executePlan({
       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: binScript(),
@@ -1075,18 +924,12 @@ async function executePlan({
     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);
   }
@@ -1103,14 +946,6 @@ async function executePlan({
 }
 
 /**
- * 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),
@@ -1119,6 +954,8 @@ async function executePlan({
  *   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 },
  *   surfaceChangelog?: (version: string) => unknown | Promise<unknown>,
+ *   gitStatus?: (opts: { cwd: string }) => { ok: boolean, staged?: string[], unstaged?: string[], tracksAgents?: boolean },
+ *   detectLockfile?: (cwd: string) => string,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
@@ -1142,6 +979,8 @@ export async function runUpdate({
   checkDrift,
   spawnPhase,
   surfaceChangelog,
+  gitStatus = defaultGitStatus,
+  detectLockfile = defaultDetectLockfile,
   write = (s) => process.stdout.write(s),
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
@@ -1163,9 +1002,7 @@ export async function runUpdate({
   }
   const target = String(await resolveTargetVersion());
 
-  // 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).
+  // Probe drift only when already newest; a real bump never calls the seam.
   const hasDrift =
     compareVersions(target, current) <= 0
       ? await resolveDrift(checkDrift)
@@ -1173,7 +1010,6 @@ export async function runUpdate({
 
   const plan = planUpdate({ current, target, dryRun, hasDrift });
 
-  // --- 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 {
@@ -1186,7 +1022,6 @@ export async function runUpdate({
     };
   }
 
-  // --- dry-run: print the plan, execute nothing -----------------------------
   if (plan.action === 'dry-run') {
     if (plan.variant === 'drift-heal') {
       write(
@@ -1219,7 +1054,6 @@ export async function runUpdate({
     };
   }
 
-  // --- resynced / updated: execute the phase plan ---------------------------
   const projectRoot = cwd();
 
   if (plan.action === 'resynced') {
@@ -1245,8 +1079,16 @@ export async function runUpdate({
   });
 
   if (plan.action === 'resynced') {
+    // No dependency is bumped here, so the re-materialized payload IS the diff.
+    const payloadLine = resolveStagingReport({
+      gitStatus,
+      detectLockfile,
+      projectRoot,
+      scope: 'payload',
+    });
     write(
-      `✅  Healed .agents/ drift (v${current}). The materialized payload is now current.\n`,
+      `✅  Healed .agents/ drift (v${current}). The materialized payload is now current.` +
+        `${payloadLine ? ` ${payloadLine}` : ''}\n`,
     );
     return {
       ok: true,
@@ -1258,7 +1100,6 @@ export async function runUpdate({
     };
   }
 
-  // plan.action === 'updated'
   if (!doctorOk) {
     return {
       ok: false,
@@ -1270,7 +1111,9 @@ export async function runUpdate({
     };
   }
 
-  write(`✅  Updated to v${target}. The lockfile bump is staged for review.\n`);
+  write(
+    `✅  Updated to v${target}. ${resolveStagingReport({ gitStatus, detectLockfile, projectRoot })}\n`,
+  );
   return {
     ok: true,
     action: 'updated',
@@ -1282,46 +1125,10 @@ export async function runUpdate({
 }
 
 /**
- * Default export consumed by `bin/mandrel.js`.
+ * Entry point for `bin/mandrel.js`: wires the production seams. `deps` exposes
+ * the process boundaries for tests only; it is not public contract.
  *
- * Wires the production-default seams that `runUpdate` leaves injectable:
- *   - `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) as
- *     `node <packageRoot>/bin/mandrel.js …` (Story #4613 — the resolved bin
- *     script, not the `node_modules/.bin` shim). 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
- *     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.
- * `--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, `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`.
- *
- * @param {string[]} argv - Subcommand arguments (after `mandrel update`).
+ * @param {string[]} argv
  * @param {{
  *   currentVersion?: string,
  *   cachePath?: string,
@@ -1336,6 +1143,8 @@ export async function runUpdate({
  *   cwd?: () => string,
  *   resolveBinScript?: (projectRoot: string) => string,
  *   checkDrift?: () => (boolean | Promise<boolean>),
+ *   gitStatus?: (opts: { cwd: string }) => object,
+ *   detectLockfile?: (cwd: string) => string,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
@@ -1361,22 +1170,15 @@ export default async function run(argv = [], deps = {}) {
     cwd,
     resolveBinScript,
     checkDrift,
+    gitStatus,
+    detectLockfile,
   } = deps;
 
   const cwdFn = typeof cwd === 'function' ? cwd : () => process.cwd();
 
-  // Story #4525/#4530: prefer the consumer's declared dependency pin over
-  // the pre-#4525 self-referential read — see resolveCurrentVersionForUpdate.
   const current =
     deps.currentVersion ?? resolveCurrentVersionForUpdate(cwdFn(), fs);
 
-  // The production spawnPhase: spawn each post-install phase as
-  // `node <packageRoot>/bin/mandrel.js …` (the newly-installed bin script,
-  // resolved layout-agnostically per Story #4613 — not the node_modules/.bin
-  // shim). 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,
@@ -1386,8 +1188,7 @@ export default async function run(argv = [], deps = {}) {
   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).
+    // An explicit update always bypasses the 24h cache.
     resolveTargetVersion: () =>
       defaultResolveTargetVersion({
         cachePath:
@@ -1405,6 +1206,10 @@ export default async function run(argv = [], deps = {}) {
         fs,
       }),
     ...(checkDrift ? { checkDrift } : {}),
+    ...(gitStatus ? { gitStatus } : {}),
+    ...(detectLockfile
+      ? { detectLockfile }
+      : { detectLockfile: (dir) => defaultDetectLockfile(dir, fs) }),
     spawnPhase: productionSpawnPhase,
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
@@ -1419,8 +1224,6 @@ export default async function run(argv = [], deps = {}) {
     writeErr,
     exit,
     cwd: cwdFn,
-    // Pass through undefined in production so runUpdate applies its default
-    // resolver (resolveNewBinScriptPath); tests inject a stub for a fake root.
     resolveBinScript,
   });
 }