hypomnema 1.8.2 → 1.9.0

package/scripts/upgrade.mjs

@@ -42,8 +42,9 @@ import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHookInventory } from './lib/hook-inventory.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
-import { templateSchemaVersion } from './lib/template-schema-version.mjs';
+import { templateSchemaVersion, schemaVersionDeltas } from './lib/template-schema-version.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
   writePkgJsonAtomic,
@@ -54,15 +55,18 @@ import {
   writeDualSkipProvenance,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
-import { writeProvenanceSidecar } from './lib/pkg-provenance.mjs';
+import { writeProvenanceSidecar, readProvenanceSidecar } from './lib/pkg-provenance.mjs';
 import { resolvePluginChannel } from './lib/plugin-detect.mjs';
 import {
   resolveGitHooksDir,
   unsafeHookTargetReason,
   parseWikiPreCommitRoot,
   wikiPreCommitContent,
+  oldFormPreCommitContent,
+  uniqueBakPath,
 } from './lib/git-hooks-dir.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
+import { atomicWrite } from '../hooks/atomic-write.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -73,6 +77,14 @@ const PKG_ROOT = join(SCRIPT_DIR, '..');
 // so the only useful next step is a re-install of the package.
 const PKG_INTEGRITY_HINT =
   '→ This indicates a corrupt or incomplete install. Re-install with `npm install -g hypomnema` (or re-install the Claude Code plugin).';
+// Where to send a person to verify after --apply. Named both ways, with no
+// runtime guess: the `hypomnema` bin comes only with the npm install, so a
+// plugin-only user has `/hypo:doctor` and nothing else, and a shell user with
+// the npm CLI may have no slash-command surface at all. Same convention
+// scripts/lib/crystallize-close-apply.mjs's own DOCTOR_HINT already uses for
+// the same reason; kept as a separate local constant here rather than an
+// import, since that file is not this task's to change.
+const DOCTOR_HINT = '`/hypo:doctor` in Claude Code, or `hypomnema doctor` with the npm CLI';
 const HOOKS_SRC = join(PKG_ROOT, 'hooks');
 const COMMANDS_SRC = join(PKG_ROOT, 'commands');
 const TEMPLATES = join(PKG_ROOT, 'templates');
@@ -132,94 +144,24 @@ function bumpType(installed, current) {
 }
 
 // ── hook map (loaded from hooks/hooks.json — single source of truth) ─────────
-
-let _hookConfig;
-try {
-  _hookConfig = JSON.parse(readFileSync(join(PKG_ROOT, 'hooks', 'hooks.json'), 'utf-8'));
-} catch {
-  console.error(`Error: cannot read hooks/hooks.json from package root: ${PKG_ROOT}`);
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-if (!_hookConfig || typeof _hookConfig !== 'object' || Array.isArray(_hookConfig)) {
-  console.error('Error: hooks/hooks.json must be a JSON object');
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-if (
-  !_hookConfig.hooks ||
-  typeof _hookConfig.hooks !== 'object' ||
-  Array.isArray(_hookConfig.hooks)
-) {
-  console.error('Error: hooks/hooks.json must contain a "hooks" object');
-  console.error(PKG_INTEGRITY_HINT);
-  process.exit(1);
-}
-function _extractCommandFileName(command) {
-  if (typeof command !== 'string') return null;
-  const matches = [...command.matchAll(/(?:^|[\/\\])([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/g)];
-  if (matches.length > 0) return matches[matches.length - 1][1];
-  const bare = command.match(/(?:^|\s)([^\/\\\s"'`]+\.mjs)(?=$|[\s"'`])/);
-  return bare ? bare[1] : null;
-}
-
-function _isHookFileName(file) {
-  return typeof file === 'string' && /^[^/\\\s]+\.mjs$/.test(file.trim());
-}
-
-function _isHookGroup(group) {
-  return (
-    group &&
-    typeof group === 'object' &&
-    !Array.isArray(group) &&
-    Array.isArray(group.hooks) &&
-    group.hooks.length > 0 &&
-    group.hooks.every(
-      (hook) =>
-        hook &&
-        typeof hook === 'object' &&
-        !Array.isArray(hook) &&
-        hook.type === 'command' &&
-        _extractCommandFileName(hook.command),
-    )
-  );
-}
-
-// Extract .mjs file names from both old format (string[]) and new format (hook-group object[])
-function _extractFileNames(groups) {
-  return groups.flatMap((group) => {
-    if (typeof group === 'string') return [group.trim()];
-    return group.hooks.map((hook) => _extractCommandFileName(hook.command));
-  });
-}
-
-for (const [event, groups] of Object.entries(_hookConfig.hooks)) {
-  const valid =
-    Array.isArray(groups) &&
-    groups.length > 0 &&
-    groups.every((group) => _isHookFileName(group) || _isHookGroup(group)) &&
-    _extractFileNames(groups).length > 0;
-  if (!valid) {
-    console.error(
-      `Error: hooks/hooks.json "hooks.${event}" must be a non-empty array of .mjs file names or Claude hook groups`,
-    );
-    console.error(PKG_INTEGRITY_HINT);
-    process.exit(1);
-  }
-}
-if (
-  _hookConfig.shared !== undefined &&
-  (!Array.isArray(_hookConfig.shared) || !_hookConfig.shared.every((f) => _isHookFileName(f)))
-) {
-  console.error('Error: hooks/hooks.json "shared" must be an array of .mjs file names');
+//
+// loadHookInventory (scripts/lib/hook-inventory.mjs) is the one parser every
+// hooks.json/shared.json consumer reads through — smoke-plugin, init, doctor,
+// and uninstall all call the same function, so a command shape one of them
+// would accept and another would silently misread cannot exist anymore. It also
+// existence-checks every named file against THIS package's own hooks/ before
+// returning ok:true, so a corrupt or incomplete package (a hook file dropped
+// from `package.json`'s `files` allowlist) fails here, at startup, instead of
+// upgrade reporting some files "src-missing" while still applying the rest.
+const _hookInventory = loadHookInventory(PKG_ROOT);
+if (!_hookInventory.ok) {
+  console.error(`Error: ${_hookInventory.error}`);
   console.error(PKG_INTEGRITY_HINT);
   process.exit(1);
 }
-
-const HOOK_MAP = Object.fromEntries(
-  Object.entries(_hookConfig.hooks).map(([e, gs]) => [e, _extractFileNames(gs)]),
-);
-const SHARED_FILES = _hookConfig.shared ?? [];
+const HOOK_MAP = _hookInventory.hookMap;
+const SHARED_FILES = _hookInventory.shared;
+const INSTALL_ORDER = _hookInventory.ordered;
 
 // ── checks ───────────────────────────────────────────────────────────────────
 
@@ -281,7 +223,16 @@ function checkGuideVersion(hypoDir) {
 function checkHookFiles(hooksDir) {
   const results = [];
 
-  const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
+  // The canonical order, shared by init and (reversed) by uninstall. Shared
+  // modules come first because applyHookFiles copies one file at a time and an
+  // entry hook imports its shared modules the moment the next event fires it:
+  // copy the entry hook first, get interrupted, and the next SessionStart dies
+  // with ERR_MODULE_NOT_FOUND, which is also the session the repair would have
+  // been run from.
+  //
+  // This is ordering, not atomicity. A half-copied set is still a mix of
+  // versions; what it is not is a set that cannot load.
+  const allFiles = INSTALL_ORDER;
   for (const file of allFiles) {
     const installedPath = join(hooksDir, file);
     const srcPath = join(HOOKS_SRC, file);
@@ -333,6 +284,51 @@ function checkSettingsJson(settingsPath, hooksDir) {
   return results;
 }
 
+// Every .mjs basename this package still ships, entry hook or shared module.
+// checkRetiredRegistrations uses it as the line between a registration we wrote
+// and have since withdrawn, and a hook somebody else put in the same directory.
+const SHIPPED_HOOK_FILES = new Set(INSTALL_ORDER);
+
+// The reverse of checkSettingsJson. That walk asks whether every live
+// HOOK_MAP entry is registered; it never asks whether a registration is still
+// live, so a settings.json install that predates a hook moving out of an event
+// keeps the old entry forever. The Stop orchestrator made that concrete: four
+// Stop hooks became steps that hypo-stop.mjs spawns, and an install that kept
+// their old Stop entries ran each of them twice per Stop.
+//
+// A registration is retired only when all three hold:
+//   - its command is exactly `node <hooksDir>/<file>` in the `$HOME` form
+//     init and checkSettingsJson write (no arguments, no subdirectory);
+//   - `<file>` is a basename this package still ships (SHIPPED_HOOK_FILES);
+//   - HOOK_MAP[event] no longer lists `<file>`.
+// A hook this package never shipped, a hypo-ext-* extension, and anything with
+// a different command shape fail the first two tests and are left alone.
+function checkRetiredRegistrations(settingsPath, hooksDir) {
+  if (!existsSync(settingsPath)) return [];
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+  const prefix = `node ${hooksDir.replace(HOME, '$HOME')}/`;
+  const found = [];
+  for (const [event, groups] of Object.entries(settings.hooks || {})) {
+    if (!Array.isArray(groups)) continue;
+    const live = new Set(HOOK_MAP[event] || []);
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) continue;
+      for (const hook of group.hooks) {
+        const cmd = hook?.command;
+        if (typeof cmd !== 'string' || !cmd.startsWith(prefix)) continue;
+        const file = cmd.slice(prefix.length);
+        if (SHIPPED_HOOK_FILES.has(file) && !live.has(file)) found.push({ event, file, cmd });
+      }
+    }
+  }
+  return found;
+}
+
 // ── apply actions ────────────────────────────────────────────────────────────
 
 // `hooksDir` is the target the stale/missing paths in `hookResults` already point
@@ -351,41 +347,162 @@ function applyHookFiles(hookResults, hooksDir) {
   return applied;
 }
 
-function applySettingsJson(settingsResults, settingsPath) {
+// ── settings.json apply: rename + add + retire as one atomic write ──────────
+//
+// These three used to be three separate `writeFileSync` calls (rename below,
+// then this file's former applySettingsJson, then its former
+// applyRetiredRegistrations), run one after another against the same file. A
+// crash mid-write could truncate the JSON; a crash BETWEEN any two of them
+// left VALID JSON that was only half-migrated. One example: a legacy Stop
+// entry renamed to its new basename with nothing left to retire it, so both
+// hypo-stop.mjs (the orchestrator) and the step it replaced fired on every
+// Stop. The retire step made that window concrete when it was added: it is
+// the step most likely to be skipped by exactly this kind of interruption.
+//
+// The fix is not three atomic writes in a row (that still leaves the
+// between-writes window) but one in-memory transform committed once. Each
+// step below reads the value the step before it just produced, never a
+// precomputed check-time snapshot. That is what keeps the self-heal
+// applySettingsJson used to need a fresh disk re-read for: a legacy
+// wiki-auto-commit.mjs entry the rename step just turned into
+// hypo-auto-commit.mjs is visible to the retire step as exactly that name,
+// in the same pass, because it is reading the same object the rename step
+// wrote into.
+
+function migrateHookNamesInSettings(settings) {
+  const applied = [];
+  for (const [event, groups] of Object.entries(settings.hooks || {})) {
+    for (const group of Array.isArray(groups) ? groups : []) {
+      for (const hook of group.hooks || []) {
+        for (const [oldName, newName] of Object.entries(HOOK_RENAMES)) {
+          if ((hook.command || '').includes(oldName)) {
+            hook.command = hook.command.replace(oldName, newName);
+            applied.push(`${event}: ${oldName} → ${newName}`);
+          }
+        }
+      }
+    }
+  }
+  return applied;
+}
+
+// Copies a renamed hook's bytes onto its new basename when the old file is
+// still on disk and the new one is not yet there. A file-system side effect,
+// not a settings.json write, so it stays separate from the atomic commit
+// below; existsSync guards make repeat runs a no-op.
+function copyRenamedHookFiles(hooksDir) {
+  for (const [oldName, newName] of Object.entries(HOOK_RENAMES)) {
+    const oldPath = join(hooksDir, oldName);
+    const newPath = join(hooksDir, newName);
+    const srcPath = join(HOOKS_SRC, newName);
+    if (existsSync(oldPath) && !existsSync(newPath) && existsSync(srcPath)) {
+      copyFileSync(srcPath, newPath);
+    }
+  }
+}
+
+// Adds every HOOK_MAP entry `settings` does not yet register, judged against
+// `settings` itself (already carrying whatever the rename step above just
+// rewrote) rather than a precomputed checkSettingsJson() list. A name the
+// rename just produced reads as already-present here, in the same pass.
+function addMissingRegistrations(settings, hooksDir) {
+  if (!settings.hooks) settings.hooks = {};
+  const applied = [];
+  for (const [event, files] of Object.entries(HOOK_MAP)) {
+    if (!Array.isArray(settings.hooks[event])) settings.hooks[event] = [];
+    for (const file of files) {
+      const cmd = `node ${hooksDir.replace(HOME, '$HOME')}/${file}`;
+      const alreadyPresent = settings.hooks[event]
+        .flatMap((g) => g.hooks || [])
+        .some((h) => h.command === cmd);
+      if (alreadyPresent) continue;
+      settings.hooks[event].push({ hooks: [{ type: 'command', command: cmd }] });
+      applied.push(`${event}: ${file}`);
+    }
+  }
+  return applied;
+}
+
+// The reverse of the add step above, judged the same way: against `settings`
+// as the add step just left it, never a precomputed checkRetiredRegistrations()
+// list computed before the rename ran. A registration is retired only when
+// all three hold, mirroring checkRetiredRegistrations's contract:
+//   - its command is exactly `node <hooksDir>/<file>` in the `$HOME` form
+//     init and checkSettingsJson write (no arguments, no subdirectory);
+//   - `<file>` is a basename this package still ships (SHIPPED_HOOK_FILES);
+//   - HOOK_MAP[event] no longer lists `<file>`.
+// This is why a legacy wiki-auto-commit.mjs entry the rename step turns into
+// hypo-auto-commit.mjs is still caught here even though hypo-auto-commit.mjs
+// never appeared in any precomputed retired list: this function never reads
+// one, only the settings the two steps above already produced. Only the
+// matching hook entries go; a group loses its whole entry only when nothing
+// else is left in it, and other keys on the group (matcher) stay with what
+// remains.
+function removeRetiredRegistrations(settings, hooksDir) {
+  const prefix = `node ${hooksDir.replace(HOME, '$HOME')}/`;
+  const retired = [];
+  for (const [event, groups] of Object.entries(settings.hooks || {})) {
+    if (!Array.isArray(groups)) continue;
+    const live = new Set(HOOK_MAP[event] || []);
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || !Array.isArray(group.hooks)) continue;
+      for (const hook of group.hooks) {
+        const cmd = hook?.command;
+        if (typeof cmd !== 'string' || !cmd.startsWith(prefix)) continue;
+        const file = cmd.slice(prefix.length);
+        if (SHIPPED_HOOK_FILES.has(file) && !live.has(file)) retired.push({ event, file, cmd });
+      }
+    }
+  }
+  if (retired.length === 0) return [];
+  const doomed = new Set(retired.map((r) => `${r.event}\n${r.cmd}`));
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = [];
+    for (const group of groups) {
+      if (group && typeof group === 'object' && Array.isArray(group.hooks)) {
+        const before = group.hooks.length;
+        group.hooks = group.hooks.filter((h) => !doomed.has(`${event}\n${h?.command}`));
+        if (before > 0 && group.hooks.length === 0) continue;
+      }
+      kept.push(group);
+    }
+    if (kept.length === 0) delete settings.hooks[event];
+    else settings.hooks[event] = kept;
+  }
+  return retired.map((r) => `${r.event}: ${r.file}`);
+}
+
+// The one place settings.json is mutated by --apply: rename, add, and retire
+// merged into a single in-memory transform, committed with exactly one
+// atomicWrite (temp file plus rename, see hooks/atomic-write.mjs). So there is
+// no window where the file on disk reflects only some of the three, and a
+// crash mid-write lands on a throwaway temp name instead of a torn
+// settings.json. Known gap this does not close: no lock guards settingsPath,
+// so a user hand-editing it in another program at the same moment can still
+// have their edit overwritten by whichever write lands last. That is the same
+// exposure the old three-write version had, just narrowed from three windows
+// to one.
+function applySettingsJsonTransform(settingsPath, hooksDir) {
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
       settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
     } catch {
-      return [];
+      return { renamed: [], added: [], retired: [] };
     }
   }
   if (!settings.hooks) settings.hooks = {};
 
-  const applied = [];
-  for (const s of settingsResults) {
-    if (s.status !== 'missing') continue;
-    if (!Array.isArray(settings.hooks[s.event])) settings.hooks[s.event] = [];
-    // re-check the current parsed settings before appending.
-    // applyHookNameMigration may have rewritten a legacy wiki-*.mjs command to
-    // exactly `s.cmd` between checkSettingsJson and now — appending without
-    // this guard creates a duplicate registration (codex 2-worker review
-    // reproduced 11 duplicate hypo-*.mjs entries on a wiki-only legacy settings
-    // file). The precheck list is allowed to be stale; the apply path must
-    // self-heal against the on-disk truth.
-    const alreadyPresent = settings.hooks[s.event]
-      .flatMap((g) => g.hooks || [])
-      .some((h) => h.command === s.cmd);
-    if (alreadyPresent) continue;
-    settings.hooks[s.event].push({ hooks: [{ type: 'command', command: s.cmd }] });
-    applied.push(`${s.event}: ${s.file}`);
-  }
+  const renamed = migrateHookNamesInSettings(settings);
+  const added = addMissingRegistrations(settings, hooksDir);
+  const retired = removeRetiredRegistrations(settings, hooksDir);
 
-  if (applied.length > 0) {
-    mkdirSync(join(settingsPath, '..'), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  if (renamed.length > 0 || added.length > 0 || retired.length > 0) {
+    atomicWrite(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   }
-  return applied;
+  if (renamed.length > 0) copyRenamedHookFiles(hooksDir);
+  return { renamed, added, retired };
 }
 
 // Rename map: old wiki-*.mjs → new hypo-*.mjs
@@ -428,45 +545,12 @@ function checkOldHookNames(settingsPath) {
   return found;
 }
 
-function applyHookNameMigration(oldRefs, settingsPath, hooksDir) {
-  if (!existsSync(settingsPath)) return [];
-
-  let settings;
-  try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-  } catch {
-    return [];
-  }
-
-  const applied = [];
-  for (const [event, groups] of Object.entries(settings.hooks || {})) {
-    for (const group of Array.isArray(groups) ? groups : []) {
-      for (const hook of group.hooks || []) {
-        for (const [oldName, newName] of Object.entries(HOOK_RENAMES)) {
-          if ((hook.command || '').includes(oldName)) {
-            hook.command = hook.command.replace(oldName, newName);
-            applied.push(`${event}: ${oldName} → ${newName}`);
-          }
-        }
-      }
-    }
-  }
-
-  if (applied.length > 0) {
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    // Copy renamed hook files to the target hooks dir (~/.claude/hooks or
-    // ~/.codex/hooks per the caller — codex mirror).
-    for (const [oldName, newName] of Object.entries(HOOK_RENAMES)) {
-      const oldPath = join(hooksDir, oldName);
-      const newPath = join(hooksDir, newName);
-      const srcPath = join(HOOKS_SRC, newName);
-      if (existsSync(oldPath) && !existsSync(newPath) && existsSync(srcPath)) {
-        copyFileSync(srcPath, newPath);
-      }
-    }
-  }
-  return applied;
-}
+// The write path used to live here as its own function (its own
+// writeFileSync). It is now the rename step inside applySettingsJsonTransform
+// above (migrateHookNamesInSettings + copyRenamedHookFiles), merged with the
+// add and retire steps into one atomic commit. checkOldHookNames above stays:
+// it is read-only, used for the report and for deciding whether there is
+// anything for --apply to do.
 
 // ── .hypoignore migration — ensure required runtime patterns are present ─────
 //
@@ -555,17 +639,42 @@ function applyGitignoreMigration(result) {
   return appended;
 }
 
-// ── wiki pre-commit hook: install-root self-heal ────────────────────────────
+// ── wiki pre-commit hook: migrate the version-pinned form to the runtime
+// resolver ───────────────────────────────────────────────────────
+//
+// init.mjs used to bake an absolute install root into the vault's pre-commit
+// hook (see the OLD form documented above PRE_COMMIT_WORKER_LINE in
+// lib/git-hooks-dir.mjs). A plugin-channel upgrade moves PKG_ROOT to a new
+// version directory every release, but nothing ever re-ran init afterward, so
+// the hook kept calling whatever release happened to be current the day
+// /hypo:init last ran — silently, since the entry-point file the hook calls is
+// often byte-identical across versions while the module graph it pulls in
+// from its own directory is not. wikiPreCommitContent() no longer bakes a
+// root in at all: the hook resolves it itself, at commit time. So the fix
+// here is not "repoint the baked root at the current install" (there is
+// nothing left to repoint once a hook is on the new form) — it is "rewrite an
+// OLD-form hook onto the new form", once, unconditionally. That migration
+// does not need to know the active install root, which is why it is safe even
+// when the registry cannot positively resolve one right now (see
+// wikiPreCommitNeedsMigration below): the resolver embedded in the rewritten
+// hook will look that up itself, fresh, at every future commit.
+//
+// Read-only: locates the hook (if any) and, only when it carries our marker in
+// a shape isOwnedWikiPreCommitBody() recognizes (old OR new — see
+// lib/git-hooks-dir.mjs), what parseWikiPreCommitRoot() read back from it.
 //
-// init.mjs bakes an absolute install root into the vault's pre-commit hook
-// (see wikiPreCommitContent in lib/git-hooks-dir.mjs). A plugin-channel upgrade
-// moves PKG_ROOT to a new version directory every release, but nothing ever
-// re-ran init afterward, so the hook keeps calling whatever release happened
-// to be current the day /hypo:init last ran — silently, since the entry-point
-// file the hook calls is often byte-identical across versions while the
-// module graph it pulls in from its own directory is not. Read-only: locates
-// the hook (if any) and, only when it carries our marker in a shape
-// wikiPreCommitContent() could have written, the root currently baked into it.
+// Returns `null` when there is nothing of ours to report (no hook, or a hook
+// with no Hypomnema marker at all: some other tool's or the user's own).
+// Returns `{ hookPath, unrecognized: true, root: null }` when our marker IS
+// present but parseWikiPreCommitRoot could not read a body it recognizes: a
+// hand-edited or corrupted hook, or (before this fix) a hook whose OLD-form
+// worker line named an install root that no longer exists. That case used to
+// collapse into the same `null` a genuinely foreign hook gets, which made
+// upgrade.mjs's report skip the "Wiki pre-commit" line entirely and left
+// doctor.mjs reporting the marker-present pass with no root warning beside
+// it: a broken hook (MODULE_NOT_FOUND on every commit) reads as installed
+// and healthy either way. `root: null` here means the same thing it does in
+// applyWikiPreCommitRoot's caller: never attempt the migration write.
 function checkWikiPreCommitRoot(hypoDir) {
   const resolved = resolveGitHooksDir(hypoDir);
   if (!resolved.ok || !resolved.owned) return null;
@@ -578,50 +687,105 @@ function checkWikiPreCommitRoot(hypoDir) {
     return null;
   }
   const parsed = parseWikiPreCommitRoot(content);
-  if (!parsed.ok) return null;
+  if (!parsed.ok) {
+    return parsed.hasMarker ? { hookPath, unrecognized: true, root: null } : null;
+  }
   return { hookPath, root: parsed.root, lintStrict: parsed.lintStrict, hypoDir: parsed.hypoDir };
 }
 
-// Rewrites ONLY the embedded root, reusing the exact writer init.mjs itself
-// uses so the regenerated hook is byte-identical to what a fresh init would
-// produce — the --lint-strict step count (info.lintStrict) is preserved
-// exactly, never collapsed to one step, or the lint gate goes silently dark.
-// The --hypo-dir baked into a --lint-strict hook is preserved from `info`
-// (what parseWikiPreCommitRoot read back), never taken from this run's own
-// --hypo-dir: upgrade can run against a vault with a different --hypo-dir than
-// the one init baked in, and substituting the current run's value would
-// silently repoint the lint gate at an unrelated directory. A non-absolute
-// embedded value is refused rather than trusted (wikiPreCommitContent()
-// re-resolves it against upgrade's own cwd, which is never what a relative
-// value there was meant to mean), leaving the hook untouched for that run.
+// Rewrites an OLD-form hook onto the runtime-resolving form, reusing the exact
+// writer init.mjs itself uses so the regenerated hook is byte-identical to
+// what a fresh init would produce today — the --lint-strict step count
+// (info.lintStrict) is preserved exactly, never collapsed to one step, or the
+// lint gate goes silently dark. The --hypo-dir baked into a --lint-strict hook
+// is preserved from `info` (what parseWikiPreCommitRoot read back), never
+// taken from this run's own --hypo-dir: upgrade can run against a vault with a
+// different --hypo-dir than the one init baked in, and substituting the
+// current run's value would silently repoint the lint gate at an unrelated
+// directory. A non-absolute embedded value is refused rather than trusted
+// (wikiPreCommitContent() re-resolves it against upgrade's own cwd, which is
+// never what a relative value there was meant to mean), leaving the hook
+// untouched for that run.
 //
-// This only self-heals the ROOT. If the vault itself has actually moved, the
-// embedded --hypo-dir is wrong too and no amount of --apply repoints it — only
-// re-running `hypomnema init` rewrites --hypo-dir.
+// `wantRoot` is accepted for call-site compatibility (the caller still
+// computes it for the drift report and JSON output) but is otherwise unused
+// here: the new form never bakes a root, so there is nothing to substitute it
+// into. This only migrates the FORM. If the vault itself has actually moved,
+// the embedded --hypo-dir is wrong too and no amount of --apply fixes that —
+// only re-running `hypomnema init` rewrites --hypo-dir.
 //
 // Returns `{ ok: true }` on a successful rewrite, or `{ ok: false, reason }`
 // naming why the write was refused or failed, so the caller can surface that
 // reason instead of silently reporting "unchanged".
-function applyWikiPreCommitRoot(info, wantRoot) {
+function applyWikiPreCommitRoot(info) {
   const unsafe = unsafeHookTargetReason(info.hookPath);
   if (unsafe) return { ok: false, reason: unsafe };
   if (info.lintStrict && !isAbsolute(info.hypoDir)) {
     return {
       ok: false,
-      reason: `embedded --hypo-dir is not absolute (${info.hypoDir}) — refusing to repoint`,
+      reason: `embedded --hypo-dir is not absolute (${info.hypoDir}) — refusing to migrate`,
     };
   }
   // hypoDir only affects output when lintStrict is true (see
   // wikiPreCommitContent); the fallback here never reaches the written file.
   const hypoDir = info.lintStrict ? info.hypoDir : '.';
-  const newContent = wikiPreCommitContent(wantRoot, hypoDir, info.lintStrict);
+
+  // Require the file ON DISK to already be, byte-for-byte, the exact OLD-form
+  // shape these SAME values (info.root, hypoDir, info.lintStrict) reconstruct.
+  // isOwnedWikiPreCommitBody upstream only validated the SPAN between the
+  // markers; it says nothing about content before the start marker or after
+  // the end one. A hand-crafted file pairing a forged-but-valid span (an
+  // old-form worker line naming a root that does not currently exist — exactly
+  // what isRewritableOldFormInstallRoot's "gone root" branch accepts) with real
+  // content outside that span would otherwise be silently discarded by the
+  // whole-file write below (codex reproduction, 2026-09-11). A legitimate
+  // install this codebase ever wrote IS exactly this reconstruction — nothing
+  // outside the span but the fixed shebang line — so this never refuses a real
+  // migration; see oldFormPreCommitContent's comment in lib/git-hooks-dir.mjs.
+  let currentContent;
+  try {
+    currentContent = readFileSync(info.hookPath, 'utf-8');
+  } catch (e) {
+    return {
+      ok: false,
+      reason: `cannot read hook to verify before migrating (${e.code || e.message})`,
+    };
+  }
+  const expectedOld = oldFormPreCommitContent(info.root, hypoDir, info.lintStrict);
+  if (currentContent !== expectedOld) {
+    return {
+      ok: false,
+      reason:
+        'hook file has content outside the managed marker span, or does not exactly match ' +
+        'the expected legacy shape — refusing to overwrite the whole file. Re-run ' +
+        "`hypomnema init --force-commands` (or the plugin's `/hypo:init --force-commands`) " +
+        'to reinstall the guard by hand',
+    };
+  }
+
+  const newContent = wikiPreCommitContent(hypoDir, info.lintStrict);
+
+  // Safety-net backup of the exact bytes about to be replaced, mirroring
+  // init.mjs's --force-commands convention (a .bak beside the hook). Guarded
+  // through the same symlink/regular-file check as the hook itself: a
+  // pre-existing `.bak` (or `.bak.N`) that is a symlink or non-regular file
+  // must not be written through, matching init's own bak-write guard.
+  const bakPath = uniqueBakPath(info.hookPath);
+  if (!bakPath) {
+    return {
+      ok: false,
+      reason: `refusing to migrate without a safe backup path (a backup name is a symlink or not a regular file)`,
+    };
+  }
+  writeFileSync(bakPath, currentContent);
+
   // A REFUSAL (above) is a soft skip, matching init's contract that an unsafe
   // or unresolvable target is logged and stepped over. A real I/O failure is
   // not that: every other apply write in this file lets the exception through,
   // and init does the same, so swallowing EACCES here would make this one
-  // self-heal quieter than the rest of --apply for no reason. It also reported
-  // the wrong thing: a chmod that fails AFTER the write says "still points at
-  // old" while the file already holds the new root.
+  // migration quieter than the rest of --apply for no reason. It also reported
+  // the wrong thing: a chmod that fails AFTER the write says "still on the old
+  // form" while the file already holds the new one.
   writeFileSync(info.hookPath, newContent);
   chmodSync(info.hookPath, 0o755);
   return { ok: true };
@@ -697,7 +861,7 @@ checklist below is manual:
       hard-required fields above
 - [ ] Run \`hypomnema feedback-sync --check\` to verify the MEMORY/CLAUDE
       projection still resolves cleanly
-- [ ] Run \`hypomnema doctor\` to verify installation health
+- [ ] Run doctor to verify installation health (\`/hypo:doctor\` in Claude Code, or \`hypomnema doctor\` with the npm CLI)
 - [ ] **Re-run \`hypomnema lint\` after backfilling — confirm 0 feedback errors
       remain (including the conditional \`claude-learned\` fields above)**
 
@@ -732,7 +896,7 @@ remaining steps are manual:
 
 - [ ] Compare your \`SCHEMA.md\` (v${fromVersion}) with the package template (v${toVersion}) and merge changes manually
 - [ ] Re-check all \`adr\` and \`learning\` pages for new required frontmatter fields once SCHEMA is updated
-- [ ] Run \`/hypo:doctor\` to verify installation health
+- [ ] Run doctor to verify installation health (\`/hypo:doctor\` in Claude Code, or \`hypomnema doctor\` with the npm CLI)
 `;
 
   const content = `---
@@ -1080,12 +1244,21 @@ const dualSkipWouldCorrect =
 // dual-install notice tells the user to remove.
 const wikiHookWantRoot = hypomnemaPluginEnabled ? pluginRegistryRoot : PKG_ROOT;
 const wikiPreCommitInfo = checkWikiPreCommitRoot(args.hypoDir);
-const wikiPreCommitDrift =
-  wikiPreCommitInfo !== null &&
-  wikiHookWantRoot !== null &&
-  wikiHookWantRoot !== wikiPreCommitInfo.root;
+// `wikiPreCommitInfo.root` is non-null only for a hook still on the
+// OLD, version-pinned form (see parseWikiPreCommitRoot in
+// lib/git-hooks-dir.mjs) — the NEW, runtime-resolving form never bakes one in,
+// so `root === null` there means "nothing to migrate", not "unresolved".
+// Migrating does not need wikiHookWantRoot at all: unlike the old repoint
+// (which had to pick the CORRECT root to bake in, and had to stay silent when
+// it could not positively resolve one — see the dual-install preserve case
+// below), rewriting onto the resolver form is always a strict improvement,
+// even when this run cannot resolve the active install itself, because the
+// rewritten hook resolves it fresh at every future commit instead of baking
+// in a guess now.
+const wikiPreCommitDrift = wikiPreCommitInfo !== null && wikiPreCommitInfo.root !== null;
 const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
+const retiredSettings = checkRetiredRegistrations(claudeSettingsPath, claudeHooksDir);
 const hypoignore = checkHypoignore(args.hypoDir);
 const gitignore = checkGitignore(args.hypoDir);
 
@@ -1095,6 +1268,9 @@ const gitignore = checkGitignore(args.hypoDir);
 const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
 const settingsCodex = args.codex ? checkSettingsJson(codexSettingsPath, codexHooksDir) : null;
 const oldHookRefsCodex = args.codex ? checkOldHookNames(codexSettingsPath) : null;
+const retiredSettingsCodex = args.codex
+  ? checkRetiredRegistrations(codexSettingsPath, codexHooksDir)
+  : null;
 
 // Extensions companion. Read-only check; the apply
 // happens below, AFTER applyCommands, so the per-target SHA map merges into the
@@ -1198,6 +1374,8 @@ let appliedHookNameRenames = [];
 let appliedHooksCodex = [];
 let appliedSettingsCodex = [];
 let appliedHookNameRenamesCodex = [];
+let appliedRetiredSettings = [];
+let appliedRetiredSettingsCodex = [];
 let appliedCommands = [];
 let appliedHypoignore = [];
 let appliedGitignore = [];
@@ -1209,28 +1387,79 @@ let appliedExtensionsCodex = null;
 if (args.apply) {
   // Downgrade guard: an `--apply` from an OLDER package than the
   // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
-  // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
+  // rewrite the version record to the older one. Refuse before the first mutation.
   // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
   // is exempt via realpath'd pkgRoot equality. Exit 2 = refused downgrade.
-  if (!args.allowDowngrade) {
-    const _active = readPkgJsonSafe(pkgJsonPath());
+  //
+  // Scoped to the two branches below that actually write a version-bearing
+  // artifact this run does not own the comparison baseline for, and each
+  // reads the baseline THAT branch actually writes, not a shared one:
+  //   - managesClaudeCore: applyHookFiles + writeProvenanceSidecar write this
+  //     run's own hooks and pkgVersion over the Claude-core hooks dir, whose
+  //     version of record is hypo-pkg.json (pkgJsonPath()) — the artifact
+  //     applyCommands below stamps. An older incoming version there really
+  //     would overwrite newer hooks.
+  //   - args.codex: reached even when managesClaudeCore is false (it is a
+  //     sibling branch, not nested under it — see :1383 below), and inside it
+  //     applyHookFiles(hooksCodex, ...) + writeProvenanceSidecar(codexHooksDir,
+  //     ..., readVersionAtRoot(PKG_ROOT), ...) copy codex hooks and stamp a
+  //     version into codexHooksDir's OWN `.hypo-provenance.json` sidecar, a
+  //     file distinct from hypo-pkg.json. A prior fix compared the codex
+  //     branch against hypo-pkg.json anyway (the Claude plugin's pointer,
+  //     unrelated to what codex hooks record their own version in) and so
+  //     never observed a downgrade there: in a dual install hypo-pkg.json
+  //     stays plugin-owned and un-bumped by a codex apply, so the "downgrade"
+  //     that guard could see was really just the plugin's untouched pointer,
+  //     leaving every SECOND `--apply --codex` refused forever (the codex
+  //     sidecar it should have compared against had already moved on).
+  //     Reading each branch's own artifact is the fix.
+  // A dualSkip run with neither condition true (the plain `--apply` repeat
+  // in a dual install, no `--codex`) copies no hook file and never writes its
+  // own version: writeDualSkipProvenance stamps the REGISTRY's version, not
+  // PKG_ROOT's, so there is nothing here for the guard to protect.
+  if ((managesClaudeCore || args.codex) && !args.allowDowngrade) {
     let _incomingVersion = null;
     try {
       _incomingVersion = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
     } catch {
       /* unreadable own package.json — cannot prove a downgrade, allow */
     }
-    if (
-      _active &&
-      _active.pkgVersion &&
-      _incomingVersion &&
-      classifyInstall(
-        { pkgRoot: PKG_ROOT, version: _incomingVersion },
-        { pkgRoot: _active.pkgRoot, version: _active.pkgVersion },
-      ) === 'downgrade'
-    ) {
-      console.error(downgradeGuardMessage(_incomingVersion, _active.pkgVersion, 'upgrade --apply'));
-      process.exit(2);
+    // `active` is { pkgRoot, pkgVersion } from whichever baseline the branch
+    // actually writes to. `label` only feeds the error message.
+    const refuseIfDowngrade = (active) => {
+      if (
+        active &&
+        active.pkgRoot &&
+        active.pkgVersion &&
+        _incomingVersion &&
+        classifyInstall(
+          { pkgRoot: PKG_ROOT, version: _incomingVersion },
+          { pkgRoot: active.pkgRoot, version: active.pkgVersion },
+        ) === 'downgrade'
+      ) {
+        console.error(
+          downgradeGuardMessage(_incomingVersion, active.pkgVersion, 'upgrade --apply'),
+        );
+        process.exit(2);
+      }
+    };
+    if (managesClaudeCore) {
+      refuseIfDowngrade(readPkgJsonSafe(pkgJsonPath()));
+    }
+    if (args.codex) {
+      // readProvenanceSidecar returns null on both "no sidecar yet" (first-
+      // ever `--apply --codex`, nothing to downgrade from) and "sidecar
+      // exists but fails to parse" — deliberately treated the same as
+      // absent, fail-open, rather than distinguished: a corrupt sidecar
+      // carries no more of a trustworthy baseline than a missing one, and
+      // the write immediately below this guard (writeProvenanceSidecar at
+      // :~1419) heals it either way. Its {pkgRoot, pkgVersion} shape matches
+      // what refuseIfDowngrade expects, unlike its `hypoSharedSha256`/
+      // `copiedAt` fields, which classifyInstall never reads.
+      const _codexActive = readProvenanceSidecar(codexHooksDir);
+      refuseIfDowngrade(
+        _codexActive && { pkgRoot: _codexActive.pkgRoot, pkgVersion: _codexActive.pkgVersion },
+      );
     }
   }
   // Migration report is vault-side (writes into the Hypomnema root) and applies
@@ -1244,13 +1473,13 @@ if (args.apply) {
     });
   }
   if (managesClaudeCore) {
-    if (oldHookRefs.length > 0) {
-      appliedHookNameRenames = applyHookNameMigration(
-        oldHookRefs,
-        claudeSettingsPath,
-        claudeHooksDir,
-      );
-    }
+    // Rename, add, and retire all commit through one atomicWrite inside this
+    // call. See applySettingsJsonTransform's own comment for why they are no
+    // longer three separate writeFileSync calls.
+    const claudeSettingsResult = applySettingsJsonTransform(claudeSettingsPath, claudeHooksDir);
+    appliedHookNameRenames = claudeSettingsResult.renamed;
+    appliedSettings = claudeSettingsResult.added;
+    appliedRetiredSettings = claudeSettingsResult.retired;
     appliedHooks = applyHookFiles(hooks, claudeHooksDir);
     // Refresh every run managesClaudeCore is true, not only when a stale hook
     // was actually copied above: applyHookFiles OVERWRITES (never skips) a
@@ -1258,7 +1487,6 @@ if (args.apply) {
     // must still keep the sidecar's pkgVersion truthful, same reasoning as
     // installHooks's own refresh-every-run comment.
     writeProvenanceSidecar(claudeHooksDir, PKG_ROOT, readVersionAtRoot(PKG_ROOT), HOOKS_SRC, false);
-    appliedSettings = applySettingsJson(settings, claudeSettingsPath);
     // applyCommands handles the single atomic hypo-pkg.json write (pkgRoot, version, schema, commands map)
     appliedCommands = applyCommands(commands, args.forceCommands);
     appliedPkgJson = true;
@@ -1350,23 +1578,19 @@ if (args.apply) {
   // wikiHookWantRoot is null only when dualSkip cannot positively resolve the
   // registry (preserve case), and wikiPreCommitDrift is already false then.
   if (wikiPreCommitDrift) {
-    const wikiPreCommitResult = applyWikiPreCommitRoot(wikiPreCommitInfo, wikiHookWantRoot);
+    const wikiPreCommitResult = applyWikiPreCommitRoot(wikiPreCommitInfo);
     appliedWikiPreCommitRoot = wikiPreCommitResult.ok;
     if (!wikiPreCommitResult.ok) wikiPreCommitApplyFailReason = wikiPreCommitResult.reason;
   }
-  // codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
-  // as the claude side (rename first so subsequent hook copy can find renamed targets).
+  // codex core hooks + settings + wiki-*→hypo-* rename mirror. Same merged,
+  // single-write transform as the claude side above.
   if (args.codex) {
-    if (oldHookRefsCodex.length > 0) {
-      appliedHookNameRenamesCodex = applyHookNameMigration(
-        oldHookRefsCodex,
-        codexSettingsPath,
-        codexHooksDir,
-      );
-    }
+    const codexSettingsResult = applySettingsJsonTransform(codexSettingsPath, codexHooksDir);
+    appliedHookNameRenamesCodex = codexSettingsResult.renamed;
+    appliedSettingsCodex = codexSettingsResult.added;
+    appliedRetiredSettingsCodex = codexSettingsResult.retired;
     appliedHooksCodex = applyHookFiles(hooksCodex, codexHooksDir);
     writeProvenanceSidecar(codexHooksDir, PKG_ROOT, readVersionAtRoot(PKG_ROOT), HOOKS_SRC, false);
-    appliedSettingsCodex = applySettingsJson(settingsCodex, codexSettingsPath);
   }
   // After applyCommands wrote hypo-pkg.json — merges extensions.<target> alongside.
   appliedExtensions = syncExtensions({
@@ -1405,7 +1629,8 @@ const codexCoreDrift =
   (staleHooksCodex.length > 0 ||
     missingSettingsCodex.length > 0 ||
     invalidSettingsCodex ||
-    (oldHookRefsCodex?.length ?? 0) > 0);
+    (oldHookRefsCodex?.length ?? 0) > 0 ||
+    (retiredSettingsCodex?.length ?? 0) > 0);
 
 // Claude core-surface drift (hooks/settings/commands/rename/metadata). In plugin
 // mode these are plugin-managed, so they must NOT count as drift — otherwise the
@@ -1420,6 +1645,7 @@ const claudeCoreDrift =
   missingSettings.length > 0 ||
   invalidSettings ||
   oldHookRefs.length > 0 ||
+  retiredSettings.length > 0 ||
   staleCommands.length > 0 ||
   userModifiedCommands.length > 0 ||
   orphanedCommands.length > 0 ||
@@ -1453,13 +1679,21 @@ if (args.json) {
         pkgJson,
         commands,
         oldHookRefs,
+        retiredSettings,
         hypoignore,
         gitignore,
         wikiPreCommitRoot: wikiPreCommitInfo
           ? {
               current: wikiPreCommitInfo.root,
+              // Not "where the hook will point": the migrated body resolves the
+              // install itself at commit time. This is what THIS run resolved the
+              // active install to, kept as diagnostic output.
               wantRoot: wikiHookWantRoot,
               drift: wikiPreCommitDrift,
+              // true only for "marker present, body unreadable" (see
+              // checkWikiPreCommitRoot above). Absent/false for both a clean
+              // new-form hook and an old-form one this run can still parse.
+              unrecognized: wikiPreCommitInfo.unrecognized === true,
             }
           : null,
         extensions: extCheck,
@@ -1468,6 +1702,7 @@ if (args.json) {
         hooksCodex,
         settingsCodex,
         oldHookRefsCodex,
+        retiredSettingsCodex,
         applied: {
           hooks: appliedHooks,
           settings: appliedSettings,
@@ -1482,6 +1717,8 @@ if (args.json) {
           hooksCodex: appliedHooksCodex,
           settingsCodex: appliedSettingsCodex,
           hookNameRenamesCodex: appliedHookNameRenamesCodex,
+          retiredSettings: appliedRetiredSettings,
+          retiredSettingsCodex: appliedRetiredSettingsCodex,
         },
         migrationReport: migrationPath,
       },
@@ -1596,6 +1833,12 @@ if (schema.bump === 'none') {
   lines.push(
     `⚠ SCHEMA version    ${schema.installed} → ${schema.current}  [minor update — review and update SCHEMA.md manually]`,
   );
+  // Name what actually changed in the versions between, when this map knows.
+  // A version this map has no entry for (installed predates the map, or a
+  // future bump forgot to add one) leaves the notice as it was above.
+  for (const delta of schemaVersionDeltas(schema.installed, schema.current)) {
+    lines.push(`                    - ${delta}`);
+  }
 }
 
 // hypo-guide.md version stamp. Visibility only — a drift warning,
@@ -1616,12 +1859,18 @@ if (guide.bump === 'none') {
   // install) but predates the version stamp entirely. Counted as drift above
   // (guideDrift) — the message must be actionable, not "cannot compare",
   // since a pre-versioning copy silently reporting "up to date" was the bug.
+  //
+  // Name both sides by their ABSOLUTE path, not the package-relative
+  // `templates/hypo-guide.md`. A person running upgrade from their vault root
+  // (the common case) has no `templates/` there at all, since init never
+  // copies that directory into the vault, so the old wording sent them
+  // looking for a file that does not exist on the machine they are standing on.
   lines.push(
-    `⚠ hypo-guide.md     installed copy has no version stamp (pre-versioning stale copy; package=v${guide.current}) — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it`,
+    `⚠ hypo-guide.md     installed copy has no version stamp (pre-versioning stale copy; package=v${guide.current}). No stamp means there is no base version to diff a changelog from, so compare and merge by hand: \`diff "${guide.pkgPath}" "${guide.hypoPath}"\`. --apply does not overwrite it`,
   );
 } else {
   lines.push(
-    `⚠ hypo-guide.md     v${guide.installed} → v${guide.current}  [package template changed — review templates/hypo-guide.md and update your copy manually; --apply does not overwrite it]`,
+    `⚠ hypo-guide.md     v${guide.installed} → v${guide.current}  [package template changed, compare and merge by hand: \`diff "${guide.pkgPath}" "${guide.hypoPath}"\`; --apply does not overwrite it]`,
   );
 }
 
@@ -1683,6 +1932,28 @@ if (managesClaudeCore) {
 }
 if (settingsCodex) pushSettingsSummary(settingsCodex, ' (codex)', invalidSettingsCodex);
 
+// Registrations a settings.json install still carries for a hook this package
+// has since moved out of that event (checkRetiredRegistrations). Silent when
+// there are none: the settings line above already says the live set is whole.
+// Under --apply this reports what was removed, which can include an entry the
+// pre-apply check could not name (a legacy wiki-*.mjs rename that landed on a
+// retired hook).
+function pushRetiredSummary(checked, applied, label) {
+  const entries = args.apply ? applied : checked.map((r) => `${r.event}: ${r.file}`);
+  if (entries.length === 0) return;
+  const colR = `settings.json${label}`.padEnd(20);
+  lines.push(
+    args.apply
+      ? `✓ ${colR}removed ${entries.length} retired registration(s):`
+      : `⚠ ${colR}${entries.length} retired registration(s) still fire. --apply removes them:`,
+  );
+  for (const e of entries) lines.push(`    - ${e}`);
+}
+if (managesClaudeCore) pushRetiredSummary(retiredSettings, appliedRetiredSettings, '');
+if (retiredSettingsCodex) {
+  pushRetiredSummary(retiredSettingsCodex, appliedRetiredSettingsCodex, ' (codex)');
+}
+
 // Package metadata
 if (dualSkip && dualSkipCorrected) {
   // npm-first correction actually WROTE this run: the pre-apply pkgJson
@@ -1735,23 +2006,37 @@ if (dualSkip && dualSkipCorrected) {
 if (wikiPreCommitInfo && wikiPreCommitDrift) {
   if (appliedWikiPreCommitRoot) {
     lines.push(
-      `✓ Wiki pre-commit   hook repointed from ${wikiPreCommitInfo.root} to ${wikiHookWantRoot}`,
+      `✓ Wiki pre-commit   hook migrated off the baked-in root ${wikiPreCommitInfo.root}` +
+        ` — it now resolves the install at commit time and no longer goes stale on a release`,
     );
   } else if (args.apply) {
     // --apply ran but the write was refused or failed — say why, rather than
     // printing the same "run --apply" nudge that already ran and did nothing.
     lines.push(
-      `⚠ Wiki pre-commit   could not repoint hook (${wikiPreCommitApplyFailReason}) — still` +
-        ` points at ${wikiPreCommitInfo.root}, active install is ${wikiHookWantRoot}`,
+      `⚠ Wiki pre-commit   could not migrate hook (${wikiPreCommitApplyFailReason}) —` +
+        ` ${wikiPreCommitInfo.root} is still baked in and goes stale on the next release`,
     );
   } else {
     lines.push(
-      `⚠ Wiki pre-commit   hook points at ${wikiPreCommitInfo.root}, active install is` +
-        ` ${wikiHookWantRoot} — run --apply to repoint it`,
+      `⚠ Wiki pre-commit   hook has ${wikiPreCommitInfo.root} baked in, so it goes stale on` +
+        ` every release — run --apply to migrate it`,
     );
   }
+} else if (wikiPreCommitInfo && wikiPreCommitInfo.unrecognized) {
+  // The marker is here but the body inside it is not one this codebase ever
+  // wrote (hand-edited, corrupted, or an install root so far gone even the
+  // rewrite-safe check above cannot read it). Nothing here is safe to
+  // rewrite automatically, so name the break instead of staying silent about
+  // it the way this branch used to (2026-09-11): a `--apply` that never
+  // prints a Wiki pre-commit line at all reads as "nothing to do" when the
+  // hook is actually failing every commit.
+  lines.push(
+    `⚠ Wiki pre-commit   marker present but the hook body is not recognized (hand-edited,` +
+      ` corrupted, or too stale to read). Run \`hypomnema init --force-commands\` (or the` +
+      ` plugin's \`/hypo:init --force-commands\`) to reinstall the guard`,
+  );
 } else if (wikiPreCommitInfo) {
-  lines.push(`✓ Wiki pre-commit   hook root up to date`);
+  lines.push(`✓ Wiki pre-commit   hook resolves the install at commit time (nothing to migrate)`);
 }
 
 // Slash commands
@@ -1972,6 +2257,7 @@ const claudeCoreCount = managesClaudeCore
     missingSettings.length +
     (invalidSettings ? 1 : 0) +
     oldHookRefs.length +
+    retiredSettings.length +
     staleCommands.length +
     userModifiedCommands.length +
     orphanedCommands.length +
@@ -2006,7 +2292,8 @@ const totalDrift =
   staleHooksCodex.length +
   missingSettingsCodex.length +
   (invalidSettingsCodex ? 1 : 0) +
-  (oldHookRefsCodex?.length ?? 0);
+  (oldHookRefsCodex?.length ?? 0) +
+  (retiredSettingsCodex?.length ?? 0);
 if (totalDrift === 0) {
   lines.push('Result: Hypomnema is up to date');
 } else if (args.apply) {
@@ -2028,8 +2315,10 @@ if (totalDrift === 0) {
     appliedExtCount +
     appliedHooksCodex.length +
     appliedSettingsCodex.length +
-    appliedHookNameRenamesCodex.length;
-  lines.push(`Result: ${total} update(s) applied. Run /hypo:doctor to verify.`);
+    appliedHookNameRenamesCodex.length +
+    appliedRetiredSettings.length +
+    appliedRetiredSettingsCodex.length;
+  lines.push(`Result: ${total} update(s) applied. Verify with ${DOCTOR_HINT}.`);
 } else {
   lines.push(`Result: ${totalDrift} item(s) need updating — run with --apply to install`);
 }