mandrel 2.60.0 → 2.61.0

package/lib/cli/update.js

@@ -1,164 +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 (manifest + lockfile rewritten on
- *      disk; whether the package manager also stages them is reported, never
- *      assumed — see § No git mutation).
- *      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 dependency bump rewrites `package.json` / the lockfile in the working
- * tree but the orchestrator performs **no** `git add` / `git commit`. This
- * module **reads git state to report it; never mutates it** (Story #5339).
- *
- * The final success line used to assert "the lockfile bump is staged for
- * review" unconditionally. That is only ever true where `npm install` happens
- * to stage; the `pnpm add` / `yarn add` seams stage nothing, so on a pnpm
- * consumer the operator was told to review an empty index while the manifest,
- * the lockfile and every re-materialized `.agents/` path sat unstaged — an
- * invitation to commit a half-upgrade. The orchestrator now probes the real
- * index through the injectable `gitStatus` seam — two read-only calls, a
- * pathspec-anchored `git status --porcelain` plus `git ls-files .agents` — and
- * prints one of three truthful lines: staged, not staged (with the exact
- * `git add` command), or a neutral "review the working tree" line when git is
- * unavailable or the probe fails. A failed probe never fails the update: the
- * run still exits 0.
- *
- * **Staged means both halves** (Story #5364): the index differs from HEAD
- * *and* the worktree agrees with the index. Reading only the index reported a
- * manifest pair the operator staged *before* running the command as staged
- * afterwards, even though the install had since rewritten both files on disk —
- * the exact false claim this report exists to remove. The drift-heal path
- * reports the re-materialized payload the same way.
- *
- * ## `--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
- *   - `gitStatus`           — read-only git probe backing the staging report;
- *                             receives `({ cwd, lockfile })` and returns
- *                             `{ ok, stagedManifest, stagedLockfile,
- *                             stagedPayload, tracksAgents }` (Story #5339,
- *                             #5364). Never mutates the repository.
- *   - `detectLockfile`      — resolves the lockfile name the staging report
- *                             names — and the probe's pathspec uses — from the
- *                             uncoerced package-manager probe, so a bun
- *                             consumer is named its real lockfile; receives
- *                             `(cwd)`
- *   - `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';
@@ -177,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}
@@ -221,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(
@@ -262,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,
@@ -317,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,
@@ -332,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'], {
@@ -368,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}
@@ -382,45 +162,26 @@ 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.
+ * 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.
  *
- * 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.
- *
- * 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);
-  // 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 };
 }
 
 /**
- * The raw, **uncoerced** package-manager probe. `detectPackageManager` above
- * flattens `bun` to `npm` for the install-command builder's benefit; the
- * staging report must not inherit that flattening, or a bun consumer is told
- * to stage a `package-lock.json` its tree does not have (Story #5364). Reading
- * the probe before the coercion is the whole fix.
+ * The uncoerced probe; the staging report must name bun's real lockfile.
  *
- * @param {string} cwd - Project root to probe.
+ * @param {string} cwd
  * @param {typeof nodeFs} [fs]
  * @returns {{ packageManager: 'pnpm'|'yarn'|'bun'|'npm', workspaceRoot: boolean }}
  */
@@ -436,24 +197,11 @@ function probePackageManager(cwd, fs = nodeFs) {
 }
 
 /**
- * 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)
+ * The install command. An `--install-cmd` override is used verbatim except
+ * that `{target}` is replaced with the resolved semver.
  *
- * 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.
- *
- * @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,
@@ -480,11 +228,6 @@ export function resolveInstallCmd(
   return `npm install ${PACKAGE_NAME}@${target}`;
 }
 
-/**
- * The lockfile each supported package manager writes. The staging report names
- * the detected one so the `git add` hint is copy-pasteable in the consumer's
- * real tree rather than always saying `package-lock.json` (Story #5339).
- */
 const LOCKFILE_BY_PACKAGE_MANAGER = {
   pnpm: 'pnpm-lock.yaml',
   yarn: 'yarn.lock',
@@ -492,23 +235,12 @@ const LOCKFILE_BY_PACKAGE_MANAGER = {
   npm: 'package-lock.json',
 };
 
-/** The manifest the dependency bump rewrites alongside the lockfile. */
 const MANIFEST_FILENAME = 'package.json';
 
-/** The materialized payload directory the sync phase rewrites. */
 const AGENTS_DIR = '.agents';
 
 /**
- * Default `detectLockfile` seam: resolve the lockfile name for the staging
- * report from the **uncoerced** package-manager probe (`pnpm-lock.yaml` /
- * `yarn.lock` / `bun.lockb` / `package-lock.json`). Reading
- * `probePackageManager` rather than `detectPackageManager` is deliberate: the
- * latter flattens `bun` to `npm` so the install-command builder has a command
- * to emit, and inheriting that here would name a lockfile the consumer's tree
- * does not carry (Story #5364). A directory with no recognizable toolchain
- * still resolves to `npm`, so the report always names a concrete file.
- *
- * @param {string} cwd - Consumer project root.
+ * @param {string} cwd
  * @param {typeof nodeFs} [fs]
  * @returns {string}
  */
@@ -517,11 +249,9 @@ export function defaultDetectLockfile(cwd, fs = nodeFs) {
   return LOCKFILE_BY_PACKAGE_MANAGER[packageManager] ?? 'package-lock.json';
 }
 
-/** The line printed when the probe cannot report the index at all. */
 const NEUTRAL_STAGING_LINE =
   'Review the working tree and commit the bump (git not available to report staging state).';
 
-/** What the probe reports when it cannot read the index at all. */
 const DEGRADED_GIT_STATE = Object.freeze({
   ok: false,
   stagedManifest: false,
@@ -530,24 +260,14 @@ const DEGRADED_GIT_STATE = Object.freeze({
   tracksAgents: false,
 });
 
-/** True when a `spawnSync` result is a clean, non-throwing exit. */
 const spawnOk = (result) =>
   Boolean(result) && !result.error && result.status === 0;
 
 /**
- * The path one `git status --porcelain` v1 record reports as **staged**, or
- * `null` when that record is not staged (or carries no path).
- *
- * Staged means both halves of the contract (Story #5364): the index differs
- * from HEAD *and* the worktree agrees with the index. Porcelain v1 states that
- * as `XY<space>path` — `X` the index column, `Y` the worktree column — so a
- * path the operator staged before the install and the install then rewrote on
- * disk reports `MM` and is correctly NOT staged. `?` in the index column is an
- * untracked file, which is never staged.
- *
- * A rename carries `orig -> new`; the post-rename path is the one the operator
- * stages. Porcelain quotes paths containing unusual bytes, so the quoting is
- * stripped.
+ * 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}
@@ -566,17 +286,10 @@ function stagedPathFromPorcelain(record) {
 }
 
 /**
- * Which slot of the probe state one staged path fills, or `null` for a path
- * that fills none.
- *
- * The payload test is anchored on a path separator, so a sibling like
- * `my.agents/` never matches, and it runs first: a `package.json` *inside*
- * `.agents/` is payload, never the consumer's root manifest. The manifest and
- * lockfile tests tolerate one leading prefix because git reports porcelain
- * paths relative to the repository root, which need not be the probe root —
- * safe only because the caller's pathspec already anchored the query there, so
- * a staged `packages/app/package.json` never reaches this function at all
- * (Story #5364).
+ * 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
@@ -591,26 +304,9 @@ function stagedSlotFor(path, lockfile) {
 }
 
 /**
- * Default `gitStatus` seam: probe the consumer repository's real index state.
- *
- * **Two** read-only plumbing calls, no mutation of any kind (§ No git
- * mutation):
- *   - `git status --porcelain -- package.json <lockfile> .agents` — one read
- *     that answers every branch the report chooses between. The pathspecs are
- *     resolved relative to `cwd`, which anchors the query at the probe root:
- *     a nested workspace manifest is simply not in the output. Both status
- *     columns come back, so "staged" can mean index-differs-**and**-worktree-
- *     clean rather than the index alone.
- *   - `git ls-files .agents` — whether the consumer *tracks* the materialized
- *     payload, which decides whether the `git add` hint names it.
- *
- * Any failure — git absent, not a repository, a non-zero exit, a throw from the
- * spawn boundary — degrades to `{ ok: false }` so the caller prints the neutral
- * line and the update still exits 0. The probe never throws.
- *
- * Security (security-baseline § Output & Rendering): every argv segment here is
- * a fixed vector or a lockfile name drawn from `LOCKFILE_BY_PACKAGE_MANAGER`,
- * never operator input, and no shell is used.
+ * 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 }`.
  *
  * @param {{
  *   cwd?: string,
@@ -659,25 +355,10 @@ export function defaultGitStatus({
 }
 
 /**
- * Render the one truthful staging line a successful run closes with
- * (Story #5339, corrected by Story #5364).
- *
- * `scope: 'bump'` (the full upgrade) reports the manifest + lockfile pair:
- *
- *   - **staged** — both are staged, so "staged for review" is a fact.
- *   - **not staged** — anything else: the line says so and prints the exact
- *     `git add` command, naming `.agents/` too when the consumer tracks that
- *     tree (the sync re-materialized it, and an operator who stages only the
- *     manifest pair silently drops that diff).
- *
- * `scope: 'payload'` (the drift heal, which bumps no dependency) reports the
- * re-materialized `.agents/` tree instead, and returns `''` when the consumer
- * does not track it — there is then nothing to stage and nothing to say.
- *
- * Either scope degrades to a line that claims nothing about the index when the
- * probe could not report.
- *
- * Pure: takes the probe result and the resolved lockfile name, touches no fs.
+ * 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.
  *
  * @param {{
  *   ok?: boolean,
@@ -685,11 +366,10 @@ export function defaultGitStatus({
  *   stagedLockfile?: boolean,
  *   stagedPayload?: boolean,
  *   tracksAgents?: boolean,
- * }} gitState - The `gitStatus` seam's return value.
- * @param {string} lockfile - The detected lockfile name.
+ * }} gitState
+ * @param {string} lockfile
  * @param {{ scope?: 'bump' | 'payload' }} [opts]
- * @returns {string} A single sentence-run with no trailing newline, or `''`
- *   when there is nothing to report.
+ * @returns {string}
  */
 export function formatStagingReport(
   gitState,
@@ -727,13 +407,8 @@ export function formatStagingReport(
 }
 
 /**
- * Resolve the staging line for a success surface, absorbing any failure in
- * either seam. Reporting the index is a courtesy on top of completed work: a
- * probe that throws (git missing, a seam raising) must degrade to the neutral
- * line, never turn a successful run into a crash.
- *
- * The lockfile is resolved first because the probe's pathspec names it — that
- * is what anchors the query at the probe root.
+ * The staging line, degrading any seam failure to the neutral line so a
+ * courtesy report never crashes a completed update.
  *
  * @param {{
  *   gitStatus: (opts: { cwd: string, lockfile: string }) => object,
@@ -762,27 +437,12 @@ function resolveStagingReport({
 }
 
 /**
- * Default `npmUpdate` seam: install the resolved target version. The install
- * rewrites `package.json` / the lockfile on disk for the operator to review;
- * this performs no git mutation. Whether the package manager also staged them
- * is reported by the staging probe, never assumed (Story #5339).
- *
- * 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.
- *
- * 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).
+ * 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 - The version to install.
+ * @param {string} target
  * @param {{
  *   installCmd?: string,
  *   runInstall?: typeof runInstallCommand,
@@ -822,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.
- *
- * 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.
+ * `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.
  *
- * 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,
@@ -888,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,
@@ -930,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`,
@@ -973,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 }>}
@@ -1008,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}.
- *
- * 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.
+ * 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.
  *
- * 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,
@@ -1044,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(
@@ -1096,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',
@@ -1120,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
@@ -1162,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: [],
@@ -1190,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 }>}
  */
@@ -1220,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: [],
@@ -1234,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 {{
@@ -1265,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: [] };
     }
@@ -1275,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' };
   }
@@ -1284,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}
@@ -1310,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>}
  */
@@ -1326,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 }>,
@@ -1364,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);
@@ -1377,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',
@@ -1390,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(),
@@ -1403,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);
   }
@@ -1431,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),
@@ -1495,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)
@@ -1505,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 {
@@ -1518,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(
@@ -1551,7 +1054,6 @@ export async function runUpdate({
     };
   }
 
-  // --- resynced / updated: execute the phase plan ---------------------------
   const projectRoot = cwd();
 
   if (plan.action === 'resynced') {
@@ -1577,10 +1079,7 @@ export async function runUpdate({
   });
 
   if (plan.action === 'resynced') {
-    // The heal re-materializes `.agents/` and stops — no dependency is bumped,
-    // so the payload IS the diff. A consumer that tracks that tree used to be
-    // told nothing at all about it (Story #5364), the same silent-diff hazard
-    // the staging report exists to close, one branch earlier.
+    // No dependency is bumped here, so the re-materialized payload IS the diff.
     const payloadLine = resolveStagingReport({
       gitStatus,
       detectLockfile,
@@ -1601,7 +1100,6 @@ export async function runUpdate({
     };
   }
 
-  // plan.action === 'updated'
   if (!doctorOk) {
     return {
       ok: false,
@@ -1613,9 +1111,6 @@ export async function runUpdate({
     };
   }
 
-  // Report the real index state rather than asserting one (Story #5339). Both
-  // seams are read-only and failure-tolerant: a probe that cannot answer yields
-  // the neutral line, and the update still reports success with a zero exit.
   write(
     `✅  Updated to v${target}. ${resolveStagingReport({ gitStatus, detectLockfile, projectRoot })}\n`,
   );
@@ -1630,46 +1125,10 @@ export async function runUpdate({
 }
 
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
- * 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; the
- *     resulting index state is reported by the staging probe, not asserted.
- *   - `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.
+ * Entry point for `bin/mandrel.js`: wires the production seams. `deps` exposes
+ * the process boundaries for tests only; it is not public contract.
  *
- * 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,
@@ -1717,18 +1176,9 @@ export default async function run(argv = [], 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,
@@ -1738,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:
@@ -1757,9 +1206,6 @@ export default async function run(argv = [], deps = {}) {
         fs,
       }),
     ...(checkDrift ? { checkDrift } : {}),
-    // Story #5339 — the staging probe. Production leaves both undefined so
-    // runUpdate applies the real read-only git seam and the lockfile detection
-    // that mirrors the install seam's; tests stub them for a fake tree.
     ...(gitStatus ? { gitStatus } : {}),
     ...(detectLockfile
       ? { detectLockfile }
@@ -1778,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,
   });
 }