baldart 3.25.0 → 3.27.0

package/src/commands/doctor.js

@@ -117,15 +117,22 @@ function overlayDrift(cwd, frameworkVersion) {
 }
 
 async function describeRemote(git, repo, offline) {
-  // Best-effort remote drift detection. Returns { ahead, behind, fetched }.
-  if (offline) return { fetched: false };
-  try { await git.fetch(repo); }
-  catch (_) { return { fetched: false }; }
-  try {
-    const out = await git.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
-    const [ahead, behind] = out.trim().split('\t').map(Number);
-    return { ahead, behind, fetched: true };
-  } catch (_) { return { fetched: false }; }
+  // SSOT (v3.25.0+): version-compare authority + diagnostic counts.
+  // The legacy { ahead, behind, fetched } shape is preserved for downstream
+  // callers that read it; the new authoritative fields are `isAligned`,
+  // `installedVersion`, `remoteVersion`.
+  if (offline) return { fetched: false, isAligned: false, installedVersion: 'unknown', remoteVersion: 'unknown', aheadScoped: 0 };
+  const status = await git.getUpdateStatus(repo);
+  return {
+    fetched: status.fetched,
+    ahead: status.commitCount.ahead,
+    behind: status.commitCount.behind,
+    isAligned: status.isAligned,
+    installedVersion: status.installedVersion,
+    remoteVersion: status.remoteVersion,
+    aheadScoped: status.aheadScoped,
+    hasFetchHead: status.hasFetchHead,
+  };
 }
 
 async function localFrameworkChanges(git) {
@@ -137,11 +144,12 @@ async function localFrameworkChanges(git) {
   } catch (_) { return 0; }
 }
 
-async function commitsAheadOfRemote(git) {
-  try {
-    const out = await git.git.raw(['rev-list', '--count', 'FETCH_HEAD..HEAD', '--', FRAMEWORK_DIR]);
-    return Number(out.trim()) || 0;
-  } catch (_) { return 0; }
+async function commitsAheadOfRemote(git, remote) {
+  // Pre-v3.25.0 this re-ran the git query; now we read from the SSOT
+  // result populated by describeRemote(). Kept as a helper for readability
+  // in detectState().
+  if (remote && typeof remote.aheadScoped === 'number') return remote.aheadScoped;
+  return 0;
 }
 
 async function detectState(cwd, opts = {}) {
@@ -206,7 +214,7 @@ async function detectState(cwd, opts = {}) {
     }
 
     state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
-    state.commitsAhead = await commitsAheadOfRemote(git);
+    state.commitsAhead = await commitsAheadOfRemote(git, state.remote);
     state.workingTreeDirty = await localFrameworkChanges(git);
 
     state.overlays = countOverlays(cwd);
@@ -577,14 +585,24 @@ function planActions(state) {
     });
   }
 
-  const remoteAhead = state.remote.fetched && state.remote.behind > 0;
-  const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
+  // v3.25.0+: drift detection is authoritative via VERSION compare (isAligned).
+  // The HEAD...FETCH_HEAD commit count is subtree-merge noise and never reaches
+  // 0, so we MUST NOT use it as the "needs update" signal.
+  const remoteAhead = state.remote.fetched && state.remote.isAligned === false;
+  // Local work detection: working-tree dirty is real; commitsAhead (aheadScoped)
+  // includes subtree-merge noise — only count it when NOT aligned (i.e. there's
+  // a real divergence to investigate). C2 adds classifier to filter noise.
+  const hasLocalWork = state.workingTreeDirty > 0 ||
+    (state.commitsAhead > 0 && state.remote.fetched && state.remote.isAligned === false);
 
   if (remoteAhead) {
+    const fromTo = (state.remote.installedVersion && state.remote.remoteVersion)
+      ? `v${state.remote.installedVersion} → v${state.remote.remoteVersion}`
+      : 'update available';
     actions.push({
       key: 'update',
-      label: `Pull ${state.remote.behind} commit(s) from upstream`,
-      why: 'Remote framework is ahead of your local copy. Updating first keeps your contributions on a fresh base.',
+      label: `Update framework (${fromTo})`,
+      why: 'Remote framework version differs from local. Updating first keeps your contributions on a fresh base.',
       autoOk: true, // update has its own internal "Proceed?" prompt + pre-flight stash
       run: () => require('./update')(),
     });
@@ -596,7 +614,7 @@ function planActions(state) {
       label: 'Push local framework improvements upstream',
       why: state.workingTreeDirty
         ? `${state.workingTreeDirty} uncommitted file(s) in .framework/ — commit them through \`baldart push\`.`
-        : `${state.commitsAhead} commit(s) on .framework/ not yet pushed.`,
+        : `${state.commitsAhead} commit(s) on .framework/ not yet pushed (may include subtree-merge noise; \`baldart push\` will classify).`,
       autoOk: false, // push writes to remote and asks for version classification — keep explicit intent
       run: () => require('./push')(),
     });
@@ -685,25 +703,39 @@ function renderDiagnostic(state) {
   }
 
   if (state.remote.fetched) {
-    const behind = state.remote.behind || 0;
-    console.log(statusLine(
-      'Remote',
-      behind > 0 ? `${behind} commit(s) ahead — update available` : 'up to date',
-      behind > 0 ? 'warn' : 'ok'
-    ));
+    // v3.25.0+: messaging based on isAligned (version-compare), not on
+    // commit count which is structurally noisy on subtree pulls.
+    if (state.remote.isAligned) {
+      console.log(statusLine(
+        'Remote',
+        `v${state.remote.remoteVersion} (aligned)`,
+        'ok'
+      ));
+    } else if (state.remote.remoteVersion && state.remote.remoteVersion !== 'unknown') {
+      console.log(statusLine(
+        'Remote',
+        `v${state.remote.remoteVersion} — update available (installed v${state.remote.installedVersion})`,
+        'warn'
+      ));
+    } else {
+      console.log(statusLine('Remote', 'upstream VERSION unreadable', 'warn'));
+    }
   } else {
     console.log(statusLine('Remote', 'offline / not fetched', 'warn'));
   }
 
-  console.log(statusLine(
-    'Local changes',
-    state.workingTreeDirty > 0
-      ? `${state.workingTreeDirty} file(s) in .framework/`
-      : state.commitsAhead > 0
-        ? `${state.commitsAhead} unpushed commit(s)`
-        : 'clean',
-    (state.workingTreeDirty + state.commitsAhead) > 0 ? 'warn' : 'ok'
-  ));
+  // Local changes: working-tree dirty is real signal. Commit count is shown
+  // ONLY if not aligned (otherwise it's subtree-merge noise — see Fix 2 for
+  // the classifier that further filters this).
+  const showCommitsAhead = state.commitsAhead > 0 &&
+    state.remote.fetched && state.remote.isAligned === false;
+  const localStatusText = state.workingTreeDirty > 0
+    ? `${state.workingTreeDirty} file(s) in .framework/`
+    : showCommitsAhead
+      ? `${state.commitsAhead} unpushed commit(s)`
+      : 'clean';
+  const localSeverity = (state.workingTreeDirty > 0 || showCommitsAhead) ? 'warn' : 'ok';
+  console.log(statusLine('Local changes', localStatusText, localSeverity));
 
   console.log(statusLine(
     'Overlays',

package/src/commands/update.js

@@ -3,6 +3,7 @@ const SymlinkUtils = require('../utils/symlinks');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const UpdateNotifier = require('../utils/update-notifier');
 
 function readEnabledTools(cwd = process.cwd()) {
   try {
@@ -108,6 +109,239 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   }
 }
 
+// --reset nuclear option (v3.26.0+).
+//
+// When the standard update keeps failing due to subtree divergence the user
+// doesn't want to investigate, --reset wipes .framework/ and reinstalls
+// cleanly. The user keeps every customization that lives OUTSIDE .framework/:
+//
+//   - baldart.config.yml          (real file, root of consumer)
+//   - .baldart/                   (whole dir: overlays/, state.json, ...)
+//   - .claude/settings.json
+//   - .claude/{agents,skills,commands}/<*.md>  ONLY if NOT a symlink into
+//                                              .framework/ (those are
+//                                              regenerated by `add`)
+//
+// Safety:
+//   - Refuses if the working tree is dirty (commit/stash first).
+//   - Refuses --yes unless --i-know is ALSO passed: --reset rm -rf's
+//     untracked & .gitignored files inside .framework/ that the user
+//     might not realize exist.
+//   - Always creates a backup tag before deleting anything.
+async function runReset(git, options, autoYes) {
+  const fs = require('fs');
+  const path = require('path');
+  const { spawnSync } = require('child_process');
+
+  UI.newline();
+  UI.header('BALDART RESET (NUCLEAR OPTION)');
+  UI.warning('This will rm -rf .framework/ and reinstall from upstream.');
+  UI.info('What is preserved (NEVER touched):');
+  UI.list([
+    'baldart.config.yml',
+    '.baldart/ (overlays, state.json, skill-conflicts.json, …)',
+    '.claude/settings.json',
+    '.claude/{agents,skills,commands}/*.md authored by you (non-framework symlinks)',
+  ], 'cyan');
+
+  // Safety gate #1: working tree MUST be clean.
+  const clean = await git.hasCleanWorkingTree();
+  if (!clean) {
+    UI.error('Working tree is dirty. Commit or `git stash -u` first, then re-run.');
+    UI.info('Reset cannot run with pending changes — too easy to lose work.');
+    process.exit(1);
+  }
+
+  // Safety gate #2: any untracked / ignored files inside .framework/?
+  let untrackedInsideFramework = '';
+  try {
+    untrackedInsideFramework = await git.git.raw([
+      'ls-files', '--others', '--ignored', '--exclude-standard', '--', '.framework/'
+    ]).catch(() => '');
+    // Some git versions return non-zero when --ignored has no matches; treat as empty.
+    if (typeof untrackedInsideFramework !== 'string') untrackedInsideFramework = '';
+  } catch (_) { untrackedInsideFramework = ''; }
+  const ignoredLines = untrackedInsideFramework.split('\n').filter((l) => l.trim());
+
+  if (ignoredLines.length) {
+    UI.newline();
+    UI.warning(`${ignoredLines.length} untracked / ignored file(s) inside .framework/ will be DELETED:`);
+    UI.list(ignoredLines.slice(0, 10), 'yellow');
+    if (ignoredLines.length > 10) UI.info(`…and ${ignoredLines.length - 10} more.`);
+    if (autoYes && options.iKnow !== true) {
+      UI.error('--reset --yes refuses to delete untracked/ignored files without --i-know.');
+      UI.info('Run: npx baldart update --reset --yes --i-know');
+      process.exit(1);
+    }
+    if (!autoYes) {
+      const ok = await UI.confirm('Proceed and DELETE these files permanently?', false);
+      if (!ok) { UI.info('Reset aborted.'); process.exit(0); }
+    }
+  }
+
+  // Safety gate #3: backup tag before doing anything destructive.
+  const backupTag = await git.createBackupTag();
+  UI.success(`Backup tag created: ${backupTag}`);
+
+  // Snapshot user-owned files OUTSIDE .framework/ for restore-after-add.
+  // All these live OUTSIDE .framework/ so `rm -rf .framework/` doesn't touch
+  // them — but we record what was present so a post-install sanity check can
+  // confirm nothing got clobbered by the fresh install flow.
+  const preserved = {
+    baldartConfig: fs.existsSync('baldart.config.yml'),
+    baldartDir: fs.existsSync('.baldart'),
+    claudeSettings: fs.existsSync(path.join('.claude', 'settings.json')),
+    customAgents: snapshotCustomEntries('.claude/agents'),
+    customSkills: snapshotCustomEntries('.claude/skills'),
+    customCommands: snapshotCustomEntries('.claude/commands'),
+  };
+  UI.info(`Preserved snapshot: config=${preserved.baldartConfig}, .baldart=${preserved.baldartDir}, settings.json=${preserved.claudeSettings}, custom files: ${preserved.customAgents.length + preserved.customSkills.length + preserved.customCommands.length}`);
+
+  // Wipe .framework/. The `git rm` first ensures git's index reflects the
+  // deletion (otherwise a stray subtree commit might recreate refs); then
+  // rm -rf removes any untracked leftovers.
+  UI.newline();
+  UI.info('Removing .framework/…');
+  try {
+    spawnSync('git', ['rm', '-rf', '--ignore-unmatch', '.framework'], { stdio: 'pipe' });
+  } catch (_) { /* fall through to rm -rf */ }
+  try {
+    fs.rmSync('.framework', { recursive: true, force: true });
+  } catch (err) {
+    UI.error(`Could not remove .framework/: ${err.message}`);
+    UI.info(`Rollback with: git reset --hard ${backupTag}`);
+    process.exit(1);
+  }
+  UI.success('.framework/ removed.');
+
+  // Commit the deletion so `subtree add` has a clean tree to land on.
+  try {
+    await git.git.add(['-A']);
+    const idx = await git.git.status();
+    if (idx.staged.length || idx.modified.length || idx.deleted.length) {
+      await git.git.commit(`chore(baldart): reset .framework/ (pre-reinstall, backup ${backupTag})`);
+      UI.success('Committed reset.');
+    }
+  } catch (err) {
+    UI.warning(`Could not commit reset (${err.message}). Continuing — subtree add may still succeed.`);
+  }
+
+  // Hand off to `add` for the fresh install. `add` will:
+  //   - `git subtree add --squash` → fresh subtree, no divergence history.
+  //   - Reconcile symlinks (custom files preserved by existing collision logic).
+  //   - Run configure if missing baldart.config.yml (we preserved it, so skip).
+  //   - Register hooks (will see existing settings.json, idempotent).
+  UI.newline();
+  UI.info('Re-installing framework via `baldart add`…');
+  const addCmd = require('./add');
+  await addCmd({ yes: true });
+
+  // Post-restore sanity check — confirm nothing user-owned got clobbered.
+  const stillPresent = {
+    baldartConfig: fs.existsSync('baldart.config.yml'),
+    baldartDir: fs.existsSync('.baldart'),
+    claudeSettings: fs.existsSync(path.join('.claude', 'settings.json')),
+  };
+  const lost = Object.entries(stillPresent).filter(([k, v]) => preserved[k] && !v).map(([k]) => k);
+  if (lost.length) {
+    UI.error(`Reset DROPPED user-owned files: ${lost.join(', ')}.`);
+    UI.info(`Rollback IMMEDIATELY: git reset --hard ${backupTag}`);
+    process.exit(1);
+  }
+
+  UI.header('✓ RESET COMPLETE');
+  UI.box('RESET RESULT', [
+    `Framework: fresh install (${await git.getFrameworkVersion()})`,
+    `Backup tag: ${backupTag}`,
+    `Rollback if needed: git reset --hard ${backupTag}`,
+    '',
+    'All user-owned files preserved.',
+  ]);
+  process.exit(0);
+}
+
+function snapshotCustomEntries(dir) {
+  const fs = require('fs');
+  const path = require('path');
+  if (!fs.existsSync(dir)) return [];
+  try {
+    return fs.readdirSync(dir)
+      .filter((name) => {
+        // Symlinks pointing into .framework/ are framework-owned (will be
+        // recreated by `add`). Real files / dirs are user-authored.
+        try {
+          const lst = fs.lstatSync(path.join(dir, name));
+          if (!lst.isSymbolicLink()) return true;
+          const target = fs.readlinkSync(path.join(dir, name));
+          return !target.includes('.framework/');
+        } catch (_) { return false; }
+      });
+  } catch (_) { return []; }
+}
+
+// CLI self-upgrade auto-relaunch (v3.25.0+).
+// When the globally-installed `baldart` CLI is older than the latest on npm,
+// transparently re-invoke `npx baldart@latest update <flags>` so the user
+// gets the fix without having to remember `npm i -g baldart@latest`. The
+// child inherits stdio (preserves prompts), and BALDART_RELAUNCHED=1 in env
+// is a loop guard: if npm cache somehow serves an older version, the child
+// sees the flag and skips its own relaunch check.
+async function maybeRelaunchUnderLatest(options) {
+  if (process.env.BALDART_RELAUNCHED === '1') return false;
+  if (process.env.BALDART_NO_RELAUNCH === '1') return false;
+
+  const cliVersion = require('../../package.json').version;
+  let info = UpdateNotifier.hint({ currentVersion: cliVersion });
+  if (!info) {
+    // No cached hint — force a refresh so a brand-new `baldart update`
+    // invocation can still benefit. Best-effort, network-bounded.
+    try {
+      await UpdateNotifier.refresh({ currentVersion: cliVersion, timeoutMs: 3000, force: true });
+      info = UpdateNotifier.hint({ currentVersion: cliVersion });
+    } catch (_) { /* offline / blocked — fall through */ }
+  }
+  if (!info) return false;
+
+  const autoYes = options.yes === true;
+  let proceed = autoYes;
+  if (!autoYes) {
+    UI.newline();
+    UI.warning(`The installed CLI is older than npm latest: v${cliVersion} → v${info.latest}.`);
+    const choice = await UI.select('How would you like to proceed?', [
+      { name: `Auto-relaunch via npx baldart@${info.latest} (recommended)`, value: 'relaunch' },
+      { name: 'Proceed with the current CLI (you may hit fixed bugs)', value: 'current' },
+      { name: 'Abort and upgrade manually (`npm i -g baldart@latest`)', value: 'abort' },
+    ]);
+    if (choice === 'abort') {
+      UI.info(`Run: npm i -g baldart@latest && npx baldart update${options.yes ? ' --yes' : ''}`);
+      process.exit(0);
+    }
+    proceed = (choice === 'relaunch');
+  }
+  if (!proceed) return false;
+
+  // Reconstruct the original argv flags for the child.
+  const flags = [];
+  if (options.yes === true) flags.push('--yes');
+  if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
+  if (options.commit === false) flags.push('--no-commit');
+  if (options.reset === true) flags.push('--reset');
+  if (options.iKnow === true) flags.push('--i-know');
+
+  const spawn = require('child_process').spawnSync;
+  UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
+  const res = spawn('npx', ['-y', `baldart@${info.latest}`, 'update', ...flags], {
+    stdio: 'inherit',
+    env: { ...process.env, BALDART_RELAUNCHED: '1' },
+    timeout: 600000, // mirror the longest legitimate flow downstream
+  });
+  if (res.error || res.status === null) {
+    UI.warning(`Auto-relaunch failed (${res.error ? res.error.message : 'no exit'}). Falling back to current CLI.`);
+    return false;
+  }
+  process.exit(res.status || 0);
+}
+
 async function update(options = {}) {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
@@ -137,6 +371,21 @@ async function update(options = {}) {
       process.exit(1);
     }
 
+    // v3.26.0+ NUCLEAR OPTION: --reset rips out .framework/ and reinstalls
+    // fresh, preserving everything user-owned that lives OUTSIDE .framework/.
+    // Branches the flow entirely — never proceeds to the standard subtree
+    // pull path.
+    if (options.reset === true) {
+      await runReset(git, options, autoYes);
+      return; // runReset exits the process on success
+    }
+
+    // v3.25.0+: CLI self-upgrade — if a newer baldart is on npm, transparently
+    // relaunch under `npx baldart@latest` so the user always runs the fixed
+    // code path. Loop guard via BALDART_RELAUNCHED env. No-op when already on
+    // latest or when the user opts out / network is down.
+    await maybeRelaunchUnderLatest(options);
+
     const currentVersion = await git.getFrameworkVersion();
     UI.success(`Current version: ${currentVersion}`);
 
@@ -168,8 +417,12 @@ async function update(options = {}) {
 
     const spinner = UI.spinner('Connecting to repository...').start();
 
+    // SSOT (v3.25.0+): one query gives version compare + commit counts +
+    // divergence class. Replaces hasChangesToPush() (which checked the wrong
+    // remote AND wrong direction — see git.js history for context).
+    let status;
     try {
-      await git.fetch(repo);
+      status = await git.getUpdateStatus(repo);
       spinner.succeed('Connected to repository');
     } catch (error) {
       spinner.fail();
@@ -187,16 +440,74 @@ async function update(options = {}) {
       process.exit(1);
     }
 
-    // Compare versions (simplified - in real scenario would fetch VERSION from remote)
-    UI.info('Checking for updates...');
+    if (!status.fetched || !status.hasFetchHead) {
+      UI.error('Could not fetch upstream — try again with network access.');
+      process.exit(1);
+    }
 
-    const hasChanges = await git.hasChangesToPush();
-    if (!hasChanges) {
-      UI.success('Already up to date!');
+    // VERSION-compare authority. Subtree-merge commit count is noise; never
+    // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
+    if (status.isAligned) {
+      UI.success(`Already up to date! (v${status.installedVersion})`);
       process.exit(0);
     }
 
-    UI.warning('Updates available!');
+    UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);
+
+    // Divergence handling: when consumer has commits on .framework/ that
+    // aren't upstream, classify before deciding. all-noise = subtree
+    // plumbing autogenerated → auto-resolve. overlay-able = user-customised
+    // a framework file → suggest /overlay. real-custom = prompt 3-way.
+    if (status.hasDivergence) {
+      UI.newline();
+      if (status.divergenceClass === 'all-noise') {
+        UI.info(`Detected ${status.divergenceCommits.length} subtree-merge / chore commit(s) (git plumbing noise — no real content drift). Auto-resolving…`);
+      } else if (status.divergenceClass === 'overlay-able') {
+        UI.warning('Detected custom edits to framework files inside `.framework/.claude/{agents,skills,commands}/`.');
+        UI.info('These are better expressed as overlays under `.baldart/overlays/` — they survive updates without divergence.');
+        for (const c of status.divergenceCommits.filter((c) => c.category === 'custom-overlay-able')) {
+          UI.info(`  • ${c.sha.slice(0, 7)} — ${c.subject}`);
+        }
+        if (autoYes) {
+          UI.error('Refusing to overwrite custom edits in --yes mode. Re-run without --yes to choose.');
+          UI.info('Recommended: use the `/overlay` skill to migrate these edits, then re-run update.');
+          process.exit(1);
+        }
+        const choice = await UI.select('How would you like to proceed?', [
+          { name: 'Migrate to overlay and pull anyway (recommended — overlay wins)', value: 'overlay' },
+          { name: 'Keep the custom commits (subtree pull may conflict)', value: 'keep' },
+          { name: 'Abort', value: 'abort' },
+        ]);
+        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+        if (choice === 'overlay') {
+          UI.info('Run `/overlay` from Claude Code to migrate the custom edits, then re-run `npx baldart update`.');
+          process.exit(0);
+        }
+        // 'keep' → fall through, subtree pull will attempt merge
+      } else if (status.divergenceClass === 'real-custom' || status.divergenceClass === 'mixed') {
+        UI.warning(`Detected ${status.divergenceCommits.filter((c) => c.category === 'custom-other').length} custom commit(s) on .framework/ that are NOT auto-classifiable as overlays.`);
+        for (const c of status.divergenceCommits.filter((c) => !['subtree-merge', 'subtree-squash', 'chore-wrapper'].includes(c.category))) {
+          UI.info(`  • ${c.sha.slice(0, 7)} [${c.category}] — ${c.subject}`);
+        }
+        if (autoYes) {
+          UI.error('Refusing to pull over custom commits in --yes mode. Re-run without --yes to choose.');
+          process.exit(1);
+        }
+        const choice = await UI.select('How would you like to proceed?', [
+          { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
+          { name: 'Pull anyway (will create a merge commit — possible conflicts)', value: 'pull' },
+          { name: 'Abort', value: 'abort' },
+        ]);
+        if (choice === 'abort') { UI.info('Update cancelled.'); process.exit(0); }
+        if (choice === 'push') {
+          UI.info('Run `/baldart-push` from Claude Code (or `npx baldart push`) to contribute upstream, then re-run update.');
+          process.exit(0);
+        }
+        // 'pull' → fall through
+      }
+      // 'unknown' → conservative: continue silently, the subtree pull will
+      // surface any real conflict.
+    }
 
     // Step 3: Show changes preview
     UI.header('STEP 3/5: Preview Changes');
@@ -412,13 +723,23 @@ async function update(options = {}) {
       if (res.malformed) {
         UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
       } else {
-        for (const r of res.results) {
-          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json (v3.18.0+ default).`);
-          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
-          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
-          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
-          // 'already' is silent on update to avoid noise
+        // Aggregate output for missing-backfill (the common case after a major
+        // bump) to keep the noise floor low. Drift events stay per-line since
+        // they represent user-visible decisions.
+        const created = res.results.filter((r) => r.status === 'created').map((r) => r.id);
+        const legacy = res.results.filter((r) => r.status === 'legacy-migrated');
+        const drifts = res.results.filter((r) => r.status === 'drift-replaced' || r.status === 'drift-kept');
+        if (created.length === 1) {
+          UI.success(`Registered hook \`${created[0]}\` in .claude/settings.json.`);
+        } else if (created.length > 1) {
+          UI.success(`Auto-registered ${created.length} missing hook(s): ${created.join(', ')}.`);
+        }
+        for (const r of legacy) UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+        for (const r of drifts) {
+          if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
         }
+        // 'already' is silent on update to avoid noise
       }
     } catch (err) {
       UI.warning(`Hook registration skipped: ${err.message}`);