hypomnema 1.8.2 → 1.9.0

package/scripts/doctor.mjs

@@ -18,6 +18,7 @@ import { homedir } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHookInventory } from './lib/hook-inventory.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 import { readRenameMarker, renameMarkerPath, RENAME_MARKER_REL } from './lib/rename-marker.mjs';
 import {
@@ -36,10 +37,12 @@ import {
   localAndUtcDates,
   normalizeVerifiedScope,
   SESSION_CLOSED_MARKER_STALE_MS,
+  sessionClosedMarkerPath,
   isUsablePkgRootLocal,
   selfLocationPkgRootFrom,
 } from '../hooks/hypo-shared.mjs';
-import { listProposals } from '../hooks/proposal-store.mjs';
+import { classifyProposals } from './proposal.mjs';
+import { listProposalsChecked, orphanTmpTargetName } from '../hooks/proposal-store.mjs';
 import {
   discoverExtensions,
   parseManifest,
@@ -64,6 +67,7 @@ import {
   computeHooksDigest,
 } from './lib/pkg-provenance.mjs';
 import { resolveCliOnPath, classifyInstall, upgradeApplyHint } from '../hooks/version-check.mjs';
+import { closeCheckpointState, isCloseComplete } from '../hooks/close-receipt.mjs';
 import {
   enabledHypomnemaPluginKey,
   usablePkgRoot,
@@ -154,94 +158,22 @@ function fail(label, detail = '') {
 }
 
 // ── 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, upgrade,
+// and uninstall all call the same function. It existence-checks every named
+// file against THIS package's own hooks/ before returning ok:true, so a
+// corrupt or incomplete doctor.mjs's OWN package (never the vault being
+// audited — that stays checkHooks()'s job below) fails here rather than
+// auditing an install against a hook list doctor cannot trust.
+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;
 
 // ── checks ───────────────────────────────────────────────────────────────────
 
@@ -338,10 +270,16 @@ function checkHooks(coreManagedByPlugin) {
   const claudeHooks = join(HOME, '.claude', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
 
-  let missing = 0;
-  for (const file of allFiles) {
-    if (!existsSync(join(claudeHooks, file))) missing++;
-  }
+  // A partial install used to only count the missing files, then stay at
+  // `warn` (rc=0). A real QA session hit exactly this: one hook file
+  // deleted, and neither the terminal output nor the exit code said which
+  // one, so an rc-gated CI job could not catch it and a user could not act
+  // on it without re-running upgrade just to find out. Naming the files
+  // reuses the same computation upgrade.mjs already does (checkHookFiles's
+  // per-file `status: 'missing'`), and `fail` gives the exit code something
+  // real to report.
+  const missingFiles = allFiles.filter((file) => !existsSync(join(claudeHooks, file)));
+  const missing = missingFiles.length;
 
   if (missing === 0) {
     pass('Hook files installed', claudeHooks);
@@ -353,7 +291,36 @@ function checkHooks(coreManagedByPlugin) {
       `provided by the plugin loader (hooks/hooks.json) — none copied to ${claudeHooks} (expected)`,
     );
   } else if (missing < allFiles.length) {
-    warn('Hook files installed', `${missing}/${allFiles.length} missing in ${claudeHooks}`);
+    // Naming the files is the part the QA incident actually asked for, so both
+    // channels get it. The exit code is not: on the plugin channel nothing the
+    // user can run copies these files (init.mjs gates installHooks on
+    // `!coreManagedByPlugin`, upgrade.mjs gates applyHookFiles on
+    // `managesClaudeCore`), so a `fail` there is a red the user cannot clear by
+    // doing anything, on every run, forever. Adding one file to
+    // hooks/shared.json is enough to put every dual install in this branch at
+    // once, which is exactly how this release found the problem.
+    //
+    // So the severity follows whether the exit code has an answer. A partial
+    // set on the plugin channel is leftovers from an earlier non-plugin
+    // install: harmless, since the loader supplies the real hooks, and worth
+    // saying out loud without failing over. checkSettingsJson below splits on
+    // the same flag for the same reason.
+    //
+    // The cost of this split: on the plugin channel a partial set stays rc=0,
+    // so an rc-gated check there still cannot see it. The file names are the
+    // only signal in that case, which is why they are printed either way.
+    const examples = missingFiles.slice(0, 3).join(', ');
+    const rest = missing > 3 ? `, +${missing - 3} more` : '';
+    const detail = `${missing}/${allFiles.length} missing in ${claudeHooks}: ${examples}${rest}`;
+    if (coreManagedByPlugin) {
+      warn(
+        'Hook files installed',
+        `${detail} — the plugin loader supplies these, so this copy is leftovers from an ` +
+          `earlier non-plugin install; nothing to fix unless you want the directory clean`,
+      );
+    } else {
+      fail('Hook files installed', `${detail}. Run /hypo:init`);
+    }
   } else {
     fail('Hook files installed', `No hook files found in ${claudeHooks} — run /hypo:init`);
   }
@@ -361,6 +328,49 @@ function checkHooks(coreManagedByPlugin) {
   checkProvenanceSidecar(claudeHooks, 'hooks/.hypo-provenance.json');
 }
 
+// Registrations for a hook this package still ships, under an event hooks.json
+// no longer maps it to. The forward walk in checkSettingsJson only asks whether
+// each live hook is registered, so an install that kept the four pre-orchestrator
+// Stop entries next to hypo-stop.mjs read as fully registered while each of those
+// steps ran twice per Stop. Same boundary as upgrade.mjs's
+// checkRetiredRegistrations, which is what removes them: the exact `$HOME`-form
+// command init writes, a basename in this package's hooks.json or shared.json,
+// and an event whose HOOK_MAP entry does not list it. Anything else (a user's own
+// hook, a hypo-ext-* extension, a command with arguments) is not ours to name.
+function retiredRegistrations(settings, hooksDir) {
+  const shipped = new Set([...Object.values(HOOK_MAP).flat(), ...SHARED_FILES]);
+  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 g of groups) {
+      if (!g || typeof g !== 'object' || !Array.isArray(g.hooks)) continue;
+      for (const h of g.hooks) {
+        if (typeof h?.command !== 'string' || !h.command.startsWith(prefix)) continue;
+        const file = h.command.slice(prefix.length);
+        if (shipped.has(file) && !live.has(file)) found.push({ event, file, cmd: h.command });
+      }
+    }
+  }
+  return found;
+}
+
+function reportRetiredRegistrations(label, retired, remedy) {
+  if (retired.length === 0) {
+    pass(label, 'None');
+    return;
+  }
+  const names = retired.map((r) => `${r.event}: ${r.file}`);
+  warn(
+    label,
+    `${retired.length} registration(s) for a hook hooks/hooks.json no longer registers under ` +
+      `that event. Each still fires on its own, on top of whatever runs it now (the Stop steps ` +
+      `are spawned by hypo-stop.mjs), so it runs twice. ${remedy}: ` +
+      `${names.slice(0, 4).join(', ')}${names.length > 4 ? `, +${names.length - 4} more` : ''}`,
+  );
+}
+
 function checkSettingsJson(coreManagedByPlugin) {
   const settingsPath = join(HOME, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) {
@@ -398,7 +408,32 @@ function checkSettingsJson(coreManagedByPlugin) {
     }
   }
 
-  if (registered === total) {
+  if (coreManagedByPlugin && registered > 0) {
+    // The plugin loader registers these hooks itself, from hooks/hooks.json.
+    // Entries in settings.json on top of that are not a second half of one
+    // install: they are a whole second registration, left over from an earlier
+    // npm or manual install, and every hook they name fires twice per event.
+    //
+    // This branch has to come before the `registered === total` pass below,
+    // which would otherwise read a full duplicate set as the healthiest
+    // possible state and print "15/15 registered". It also has to come before
+    // the partial-warn, whose `/hypo:init` prescription does nothing here:
+    // init.mjs skips mergeSettingsJson entirely on this channel.
+    //
+    // Left as warn rather than fail: doctor has never removed a settings entry
+    // and guessing which hook group belongs to Hypomnema is how it would start
+    // deleting someone else's. Saying the state out loud, with the exact
+    // command prefix to look for, is what doctor can do honestly. The cost is
+    // that an rc-gated check still cannot see a double-firing install.
+    warn(
+      'settings.json hook registrations',
+      `${registered}/${total} Hypomnema hook(s) also registered in settings.json while the plugin ` +
+        `loader is active — these fire on top of the plugin's own, so each one runs twice. ` +
+        `They are leftovers from an earlier npm or manual install: remove the entries whose ` +
+        `command starts with \`node ${hooksDir.replace(HOME, '$HOME')}/hypo-\` from settings.json, ` +
+        `or run /hypo:uninstall before reinstalling the plugin`,
+    );
+  } else if (registered === total) {
     pass('settings.json hook registrations', `${registered}/${total} registered`);
   } else if (registered > 0) {
     warn(
@@ -421,6 +456,11 @@ function checkSettingsJson(coreManagedByPlugin) {
   // so they are intentionally absent from HOOK_MAP. Excluded here; their
   // integrity (SHA + manifest + entry match) is checked separately in E5.
   const isExtCommand = (cmd) => /(?:^|[/\s])hypo-ext-[^/\s]+\.mjs(?=$|["'\s])/.test(cmd);
+  // Retired registrations get their own line with a prescription that works
+  // (upgrade --apply removes them); listing them here as well would print the
+  // same entry twice under a remedy that does not.
+  const retired = retiredRegistrations(settings, hooksDir);
+  const retiredCmds = new Set(retired.map((r) => r.cmd));
   const expectedCmds = new Set(
     Object.entries(HOOK_MAP).flatMap(([, files]) =>
       files.map((f) => `node ${hooksDir.replace(HOME, '$HOME')}/${f}`),
@@ -436,7 +476,8 @@ function checkSettingsJson(coreManagedByPlugin) {
           typeof h.command === 'string' &&
           /hypo-[^/]+\.mjs/.test(h.command) &&
           !isExtCommand(h.command) &&
-          !expectedCmds.has(h.command)
+          !expectedCmds.has(h.command) &&
+          !retiredCmds.has(h.command)
         ) {
           stale.push(h.command);
         }
@@ -451,6 +492,15 @@ function checkSettingsJson(coreManagedByPlugin) {
   } else {
     pass('settings.json stale hypo-* entries', 'None');
   }
+  reportRetiredRegistrations(
+    'settings.json retired hook registrations',
+    retired,
+    // upgrade --apply leaves settings.json alone on the plugin channel, so it
+    // is not a remedy there.
+    coreManagedByPlugin
+      ? 'Remove them from settings.json by hand'
+      : 'Run /hypo:upgrade (or `hypomnema upgrade --apply`) to remove them',
+  );
 
   // duplicate hypo-* entries per event
   const dupes = [];
@@ -477,6 +527,71 @@ function checkSettingsJson(coreManagedByPlugin) {
   }
 }
 
+// ── dual install (plugin + manual/npm core hook conflict) ────────────────────
+//
+// A plugin-channel install and a manual/npm install can both register
+// the SAME core hooks from two different PKG_ROOTs, and each hooks/hypo-shared.mjs
+// copy resolves its own root by self-location, so nothing forces the two to agree
+// — one hook can call v1.7.0's scripts/ while another in the same session calls
+// v1.7.1's. upgrade.mjs already detects this (dualInstallCoreConflict/dualSkip)
+// and skips double-registering on --apply; the 2026-09-08 policy investigation's
+// recommendation was for doctor to report the same state on every run, not only
+// when upgrade happens to be invoked. `pluginChannel` above is computed once via
+// the SAME resolvePluginChannel() upgrade.mjs and init.mjs call
+// (lib/plugin-detect.mjs) — this reuses that judgment rather than re-deriving it.
+// `hypomnemaPluginEnabled` is `reason !== 'not-enabled'`, so it stays true when the
+// registry could not be read or the enabled key resolved to no install on disk. Both
+// mean settings NAMES a plugin whose files were not located, which is a different
+// state from "two installs are really present". checkPkgIntegrity below asks the same
+// question, so the two share this name rather than each spelling the pair out.
+function channelJudgmentFailed(pluginChannel) {
+  return (
+    pluginChannel.hypomnemaPluginEnabled &&
+    (pluginChannel.rootReason === 'registry-unreadable' ||
+      pluginChannel.rootReason === 'unresolved')
+  );
+}
+
+function checkDualInstall(pluginChannel) {
+  const { pluginMode, hypomnemaPluginEnabled } = pluginChannel;
+  if (pluginMode) {
+    pass(
+      'Dual install (plugin + manual/npm)',
+      'Running as the plugin install — no manual/npm registration to conflict with',
+    );
+    return;
+  }
+  if (!hypomnemaPluginEnabled) {
+    pass('Dual install (plugin + manual/npm)', 'Manual/npm install only — plugin not enabled');
+    return;
+  }
+  // Not a dual install: telling this user to `npm uninstall -g hypomnema` would remove
+  // the only copy they actually have. A stale `enabledPlugins` entry left behind by an
+  // uninstall is exactly this shape.
+  if (channelJudgmentFailed(pluginChannel)) {
+    warn(
+      'Dual install (plugin + manual/npm)',
+      `~/.claude/settings.json enables the Hypomnema plugin, but the registry says ` +
+        `\`${pluginChannel.rootReason}\` — the plugin's files could not be located, so whether this is a ` +
+        `real dual install is UNDETERMINED. Do not remove the npm/manual copy on the strength ` +
+        `of this line: if the plugin is not actually installed, that copy is the only one you ` +
+        `have. Check ~/.claude/plugins/installed_plugins.json, then either re-install the ` +
+        `plugin or drop the stale entry from enabledPlugins.`,
+    );
+    return;
+  }
+  warn(
+    'Dual install (plugin + manual/npm)',
+    'The Hypomnema plugin is ALSO enabled in ~/.claude/settings.json while this is the ' +
+      'manual/npm install — the plugin loader already provides the core hooks, slash ' +
+      'commands, and settings.json wiring, and /hypo:upgrade skips re-registering them by ' +
+      'default (doing so would fire every core hook twice). Pick one install: remove the ' +
+      'npm/manual copy (`npm uninstall -g hypomnema`) and upgrade via `/plugin marketplace ' +
+      'update hypomnema`, or run `hypomnema upgrade --apply --allow-dual-install` to ' +
+      'knowingly register both.',
+  );
+}
+
 function checkGit(hypoDir) {
   if (!existsSync(join(hypoDir, '.git'))) {
     warn(
@@ -543,15 +658,38 @@ function checkGit(hypoDir) {
     // plugin-cache leaf-drift precedent: reporting must never turn into
     // filtering, or a still-real, still-resolvable root looks like it vanished).
     const parsedRoot = parseWikiPreCommitRoot(content);
-    const wantRoot = resolveDurableHookRoot();
-    if (parsedRoot.ok && wantRoot !== null && wantRoot !== parsedRoot.root) {
+    if (parsedRoot.ok && parsedRoot.root === null) {
+      // The runtime-resolving form: the hook looks up its own
+      // install root at commit time, so there is no baked value to compare
+      // against the active install — it cannot structurally go stale the way
+      // the old, version-pinned form could. Report that fact in place of the
+      // stale-root comparison below, rather than falling silent.
+      pass(`${label} root`, 'Resolved at commit time by the hook itself — never goes stale');
+    } else if (!parsedRoot.ok) {
+      // The pass above only checked that our START marker is present, not
+      // that the body it wraps is one this codebase can actually run. This is
+      // the fail-open this branch used to leave: a hand-edited body, a
+      // corrupted one, or (before the rewrite-safe root check) an OLD-form
+      // hook whose baked-in install root no longer existed all read as a
+      // clean "guard installed" pass while the hook fails MODULE_NOT_FOUND on
+      // every real commit.
       warn(
         `${label} root`,
-        `Points at an old install root (${parsedRoot.root}) — the active install is ` +
-          `${wantRoot}. To repoint it, run ${upgradeApplyHint(
-            pluginMode || hypomnemaPluginEnabled,
-          )}.`,
+        'Guard marker present but the hook body is not recognized, it may be failing on ' +
+          `every commit. Run \`hypomnema init --force-commands\` (or the plugin's ` +
+          `\`/hypo:init --force-commands\`) to reinstall it.`,
       );
+    } else {
+      const wantRoot = resolveDurableHookRoot();
+      if (wantRoot !== null && wantRoot !== parsedRoot.root) {
+        warn(
+          `${label} root`,
+          `Points at an old install root (${parsedRoot.root}) — the active install is ` +
+            `${wantRoot}. To repoint it, run ${upgradeApplyHint(
+              pluginMode || hypomnemaPluginEnabled,
+            )}.`,
+        );
+      }
     }
   } else {
     warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');
@@ -1033,6 +1171,10 @@ function checkSessionCloseArtifacts(hypoDir) {
   // already-expired marker can't vouch for anything.
   const cacheDir = join(hypoDir, '.cache');
   const markers = [];
+  // Markers closeCheckpointState does not call a finished close (the receipt
+  // they name is missing, invalid or another generation, or a valid receipt
+  // disagrees with them). They cover nothing, and the warning says why.
+  const brokenMarkers = [];
   let cacheEntries = [];
   if (existsSync(cacheDir)) {
     try {
@@ -1047,6 +1189,19 @@ function checkSessionCloseArtifacts(hypoDir) {
       const data = JSON.parse(readFileSync(join(cacheDir, file), 'utf-8'));
       const ts = Date.parse(data?.closed_at || '');
       if (!Number.isFinite(ts) || Date.now() - ts > SESSION_CLOSED_MARKER_STALE_MS) continue;
+      // The same verdict Stop blocks on, fed the marker parsed above so the
+      // reader never unlinks anything. The file name carries the sanitized id,
+      // which can differ from the real one; the marker body carries the real
+      // one, and the receipt's own session id check needs exactly that.
+      const sessionId =
+        typeof data?.session_id === 'string' && data.session_id
+          ? data.session_id
+          : file.slice('session-closed-'.length, -'.marker'.length);
+      const checkpoint = closeCheckpointState(hypoDir, sessionId, { marker: data });
+      if (!isCloseComplete(checkpoint)) {
+        brokenMarkers.push({ sessionId, reason: checkpoint.reason });
+        continue;
+      }
       // ONLY the v4 `projects` array counts as project-scope evidence. A
       // legacy flat `project` field can be a recency-derived misattribution
       // (the P1 bug resolveCloseScope's own doc comment describes) — the
@@ -1086,6 +1241,15 @@ function checkSessionCloseArtifacts(hypoDir) {
     .map((a) => `${a.where}${a.date ? ` (${a.date})` : ''}`)
     .join(', ');
   const extra = unmatched.length > 5 ? ` (+${unmatched.length - 5} more)` : '';
+  const brokenNote =
+    brokenMarkers.length > 0
+      ? `. ${brokenMarkers.length} session-closed marker(s) did not count because their close ` +
+        `checkpoint is broken: ` +
+        brokenMarkers
+          .slice(0, 3)
+          .map((b) => `${b.sessionId} (${b.reason})`)
+          .join('; ')
+      : '';
   // Not necessarily UNAPPROVED — an approved log-only marker (deliberately
   // empty `projects`) or one scoped to a different project would ALSO land
   // here, since neither covers a specific project's artifact. Both readings
@@ -1095,7 +1259,65 @@ function checkSessionCloseArtifacts(hypoDir) {
     'Session-close artifacts',
     `${unmatched.length} close artifact(s) with no session-closed marker covering their ` +
       `date and project scope — may be an unapproved hand-made close, or an approved close ` +
-      `whose marker doesn't attribute this project: ${sample}${extra}`,
+      `whose marker doesn't attribute this project: ${sample}${extra}${brokenNote}`,
+  );
+}
+
+// A close receipt with no session-closed marker beside it is a half-finished
+// close (the run stopped before the marker landed, or only the marker was
+// invalidated). checkSessionCloseArtifacts starts from close artifacts and
+// then walks markers, so this state is invisible to it. Enumerate the
+// receipts instead, judge each markerless one with the verdict Stop blocks
+// on, and stay silent otherwise. Same 7-day window as the marker walk, read
+// off the receipt file's mtime.
+function checkHalfClosedReceipts(hypoDir) {
+  const sessionsDir = join(hypoDir, '.cache', 'sessions');
+  let dirs = [];
+  try {
+    dirs = readdirSync(sessionsDir);
+  } catch {
+    return; // no sessions directory, or unreadable: nothing to judge
+  }
+  const broken = [];
+  for (const name of dirs) {
+    const file = join(sessionsDir, name, 'close-receipt.json');
+    try {
+      if (Date.now() - statSync(file).mtimeMs > SESSION_CLOSED_MARKER_STALE_MS) continue;
+      // The directory name is the sanitized id; the receipt body carries the real one.
+      const body = JSON.parse(readFileSync(file, 'utf-8'));
+      const sessionId =
+        typeof body?.sessionId === 'string' && body.sessionId ? body.sessionId : name;
+      if (existsSync(sessionClosedMarkerPath(hypoDir, sessionId))) continue;
+      const checkpoint = closeCheckpointState(hypoDir, sessionId, { marker: null });
+      if (checkpoint.state !== 'broken') continue;
+      // --mark-session-closed refuses a receipt whose commit is no longer an
+      // ancestor of HEAD (history rewritten), so do not offer it for that case.
+      const commit = typeof body?.commit === 'string' ? body.commit : '';
+      const rewritten =
+        /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(commit) &&
+        spawnSync('git', ['-C', hypoDir, 'rev-parse', '--verify', '--quiet', 'HEAD']).status ===
+          0 &&
+        spawnSync('git', ['-C', hypoDir, 'merge-base', '--is-ancestor', commit, 'HEAD']).status !==
+          0;
+      broken.push({ sessionId, reason: checkpoint.reason, rewritten });
+    } catch {
+      // unreadable or corrupt receipt: not this check's job to diagnose
+    }
+  }
+  if (broken.length === 0) return;
+  const crystallize = join(PKG_ROOT, 'scripts', 'crystallize.mjs');
+  warn(
+    'Session-close checkpoint',
+    `${broken.length} session(s) hold a close receipt but no session-closed marker: ` +
+      broken
+        .slice(0, 3)
+        .map((b) =>
+          b.rewritten
+            ? `${b.sessionId} (${b.reason}; the commit it certified is no longer in this branch's history). Restore that commit, or ask the user to close again and apply it with /hypo:crystallize`
+            : `${b.sessionId} (${b.reason}). Recover with: node "${crystallize}" --mark-session-closed --session-id=${b.sessionId}`,
+        )
+        .join('; ') +
+      (broken.length > 3 ? ` (+${broken.length - 3} more)` : ''),
   );
 }
 
@@ -1272,38 +1494,195 @@ function checkProjectSuggestions(hypoDir) {
 }
 
 function checkProposals(hypoDir) {
-  // Vault-wide count of parked write-proposals (T8). listProposals is the
-  // count source rather than a raw readdir: it already skips malformed and
-  // spoofed-id artifacts, so the number matches exactly what `hypomnema proposal
-  // list/apply/discard` can act on. Surface only: warn (never fail), pass at 0,
-  // because a pending proposal is a normal state awaiting review, not a broken
-  // install, and the check discovers without changing any state.
-  const count = listProposals(hypoDir).length;
-  if (count === 0) {
-    pass('Pending proposals', 'No parked write-proposals');
-  } else {
+  // Surface only: warn (never fail), pass at 0, because a parked proposal is a
+  // normal state awaiting a human rather than a broken install, and this check
+  // discovers without changing anything.
+  //
+  // Ask the store directly FIRST, before classifying anything. `ok: false`
+  // means `.cache/proposals` itself could not be listed (permission denied,
+  // or a file sitting where the directory should be): the backlog is
+  // unmeasured, not zero. classifyProposals reads listProposals underneath,
+  // which folds that same readdir failure into `[]` (right for its own
+  // callers, which want a best-effort listing, wrong for a health check), so
+  // classifying first and asking the store second let an unmeasured backlog
+  // slip through the `classified.length === 0` gate below and report a
+  // lying pass. This warn branch used to read
+  // `inventory.ok ? inventory.unreadable : []`, which threw away `ok: false`
+  // entirely and fell straight into that same lying pass.
+  const inventory = listProposalsChecked(hypoDir);
+  if (!inventory.ok) {
     warn(
       'Pending proposals',
-      `${count} parked write-proposal(s) awaiting review; inspect with \`hypomnema proposal list\``,
+      `${join(hypoDir, '.cache', 'proposals')} could not be listed (permission denied, or a ` +
+        `file sitting where the directory should be): the parked write-proposal count is ` +
+        `unmeasured here, not zero. Run \`ls -la ${join(hypoDir, '.cache', 'proposals')}\` to ` +
+        `see what is blocking it, then fix the permissions or remove the stray file.`,
+    );
+    return;
+  }
+  const unreadable = inventory.unreadable;
+
+  // Not a count of artifacts. Three different states share that shape and want
+  // three different things from the user, and telling them apart needs the
+  // audit log and the page's current hash, which is exactly the judgment
+  // `proposal reconcile` makes. Reuse that judgment rather than derive a second
+  // one here: the failure this closes is a doctor that told the user to review
+  // a write a human had already approved and that was already on the page.
+  const classified = classifyProposals(hypoDir);
+  const pending = classified.filter((c) => c.kind === 'pending');
+  const recoverable = classified.filter((c) => c.kind === 'recoverable');
+  const broken = classified.filter((c) => c.kind === 'evidence-broken');
+
+  if (classified.length === 0 && unreadable.length === 0) {
+    pass('Pending proposals', 'No parked write-proposals');
+    return;
+  }
+  const parts = [];
+  if (recoverable.length > 0) {
+    parts.push(
+      `${recoverable.length} approved and already written, but their close handoff receipt ` +
+        `never landed: run \`hypomnema proposal reconcile\` (it recovers the receipt from ` +
+        `evidence and writes no page). Do NOT re-run the close first`,
+    );
+  }
+  if (broken.length > 0) {
+    parts.push(
+      `${broken.length} whose audit entry no longer matches the page (${broken
+        .slice(0, 3)
+        .map((c) => c.target)
+        .join(', ')}): neither reconcile nor a re-close can settle these without a human`,
+    );
+  }
+  if (pending.length > 0) {
+    // No drain to advertise: reconcile never removes a 'pending' artifact (see the
+    // note above reconcileProposals). `list` shows age and target activity so a
+    // human can triage, and every removal is their own `discard`.
+    parts.push(
+      `${pending.length} awaiting review; inspect with \`hypomnema proposal list\` ` +
+        `(it shows each one's age and whether its target moved since)`,
+    );
+  }
+  if (unreadable.length > 0) {
+    parts.push(
+      `${unreadable.length} candidate file(s) in .cache/proposals could not be read or ` +
+        `parsed (corrupt, permission-denied, or hand-edited): ${unreadable
+          .slice(0, 3)
+          .join(', ')}${unreadable.length > 3 ? `, +${unreadable.length - 3} more` : ''}; ` +
+        `neither \`proposal list\` nor \`proposal reconcile\` sees these. Run ` +
+        `\`ls -la ${join(hypoDir, '.cache', 'proposals')}\` to see the rest and open each file ` +
+        `directly`,
     );
   }
+  // Separate sentence, not folded into the wording above: an orphan tmp file
+  // is a subset of `unreadable` (a name can sit in both arrays, see
+  // scanProposalFiles), but it is not corrupt and not hand-edited. It is a
+  // complete proposal body whose rename from `<id>.json.<pid>.<rand>.tmp` to
+  // `<id>.json` never landed, so the fix is `mv`, not deletion.
+  const orphanTmp = inventory.orphanTmp || [];
+  if (orphanTmp.length > 0) {
+    const proposalsDir = join(hypoDir, '.cache', 'proposals');
+    const hints = orphanTmp
+      .slice(0, 3)
+      .map(
+        (name) =>
+          `mv "${join(proposalsDir, name)}" "${join(proposalsDir, orphanTmpTargetName(name))}"`,
+      )
+      .join('; ');
+    parts.push(
+      `${orphanTmp.length} of the file(s) above are recoverable, not corrupt: a writer finished ` +
+        `serializing a proposal body but crashed before the rename to its \`.json\` name landed. ` +
+        `Restore with, e.g., \`${hints}\`${orphanTmp.length > 3 ? ` (+${orphanTmp.length - 3} more, same pattern: drop the \`.<pid>.<rand>.tmp\` suffix)` : ''}`,
+    );
+  }
+  warn('Pending proposals', parts.join('. '));
+}
+
+/**
+ * Surface leftover `.cache/close-intent/` records: crystallize-close-apply's
+ * torn-set witness (see closeIntentPath's doc comment there). A record
+ * outlives its close only when that close crashed between writeCloseIntent
+ * and clearCloseIntent, so every one found here means an interrupted apply,
+ * never a normal state to leave silent. Read-only: whether an aged-out
+ * record gets deleted is hasTornCloseIntent's call, made the next time a
+ * close actually runs the probe, not doctor's.
+ */
+function checkCloseIntent(hypoDir) {
+  const dir = join(hypoDir, '.cache', 'close-intent');
+  if (!existsSync(dir)) {
+    pass('Close-intent records', 'No leftover .cache/close-intent/ records');
+    return;
+  }
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (e) {
+    // The same failure hasTornCloseIntent treats as 'unreadable' rather than
+    // silently torn: this check cannot tell either, so it says so instead of
+    // reporting a clean count that might be a lie.
+    warn(
+      'Close-intent records',
+      `${dir} could not be listed (${e.code || e.message}): whether a leftover record is sitting ` +
+        `there is unmeasured, not zero, and every no-payload close probe against this vault treats ` +
+        `an unreadable directory as unresolved (payload required) until this is fixed. Run ` +
+        `\`ls -la ${dir}\` to see what is blocking it.`,
+    );
+    return;
+  }
+  const records = names.filter((n) => n.endsWith('.json'));
+  if (records.length === 0) {
+    pass('Close-intent records', 'No leftover .cache/close-intent/ records');
+    return;
+  }
+  let unreadableCount = 0;
+  let oldestMinutes = null;
+  for (const name of records) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(dir, name), 'utf-8'));
+      const ts = Date.parse(parsed?.startedAt);
+      if (Number.isFinite(ts)) {
+        const minutes = Math.round((Date.now() - ts) / 60_000);
+        if (oldestMinutes === null || minutes > oldestMinutes) oldestMinutes = minutes;
+        continue;
+      }
+    } catch {
+      // falls through to unreadableCount below
+    }
+    unreadableCount++;
+  }
+  const parts = [
+    `${records.length} record(s) in .cache/close-intent/, left behind by a close that began ` +
+      `writing and never called clearCloseIntent (a crash or a killed session mid-apply, or a close that ended ok:false before its commit landed)`,
+  ];
+  if (oldestMinutes !== null) parts.push(`oldest is ${oldestMinutes} minute(s) old`);
+  if (unreadableCount > 0) {
+    parts.push(
+      `${unreadableCount} could not be read or parsed, so its age is unknown; every no-payload ` +
+        `close probe for this vault treats an unreadable record the same as a torn one (payload ` +
+        `required) until it is removed`,
+    );
+  }
+  warn('Close-intent records', parts.join('; '));
 }
 
 function checkCodexPaths() {
   const codexHooks = join(HOME, '.codex', 'hooks');
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
 
-  let missing = 0;
-  for (const file of allFiles) {
-    if (!existsSync(join(codexHooks, file))) missing++;
-  }
+  // Names the files for the same reason checkHooks above does: a count alone
+  // leaves the user re-running upgrade just to find out which one. The severity
+  // stays warn here rather than following checkHooks to fail, because this
+  // channel is opt-in and nothing reads its exit code.
+  const missingFiles = allFiles.filter((file) => !existsSync(join(codexHooks, file)));
+  const missing = missingFiles.length;
 
   if (missing === 0) {
     pass('Codex hook files installed', codexHooks);
   } else if (missing < allFiles.length) {
+    const examples = missingFiles.slice(0, 3).join(', ');
+    const rest = missing > 3 ? `, +${missing - 3} more` : '';
     warn(
       'Codex hook files installed',
-      `${missing}/${allFiles.length} missing in ${codexHooks} — run /hypo:init --codex`,
+      `${missing}/${allFiles.length} missing in ${codexHooks}: ${examples}${rest} — run /hypo:init --codex`,
     );
   } else {
     fail(
@@ -1359,6 +1738,11 @@ function checkCodexPaths() {
       `0/${total} registered — run /hypo:init --codex`,
     );
   }
+  reportRetiredRegistrations(
+    'Codex settings.json retired hook registrations',
+    retiredRegistrations(settings, hooksDir),
+    'Run `hypomnema upgrade --apply --codex` to remove them',
+  );
 }
 
 // ── extensions integrity (E5) ─────────────────────────────────────
@@ -2281,13 +2665,56 @@ function checkProvenanceSidecar(hooksDir, label) {
 // trusts.
 //
 // Returns null when there is nothing to report (field absent, or digests
-// match), or a ready-to-append reason string naming a few diverged files.
+// match), or a ready-to-append reason string: either a diverged-files
+// mismatch, or the "cannot verify" case below.
 function hooksDigestMismatch(hooksDir, recordedDigest) {
   if (typeof recordedDigest !== 'string' || !recordedDigest) return null;
   const actualDigest = computeHooksDigest(PKG_ROOT, hooksDir);
-  if (actualDigest === null || actualDigest === recordedDigest) return null;
+  if (actualDigest === recordedDigest) return null;
 
   const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
+
+  // computeHooksDigest returns null for two different reasons, and neither is
+  // "the digests matched": either hooks.json itself could not be read from
+  // PKG_ROOT, or one of the files it lists could not be read out of hooksDir.
+  // This branch used to be folded into the early return as
+  // `if (actualDigest === null || actualDigest === recordedDigest) return null`,
+  // which reported a failed recompute as nothing-to-report, so a deleted hook
+  // file still printed `verified`. "Could not verify" has to stay a distinct,
+  // non-silent state from "verified". It is not promoted to fail here because
+  // checkProvenanceSidecar keeps this label warn-or-pass, never fail, same as
+  // every other branch in that function, and checkHooks() above already
+  // names the same deletion as a fail, so the exit code is covered there.
+  //
+  // Of those two causes only the second can reach this line: loadHookInventory
+  // reads the same two JSON files at module load and exits 1 when they are bad,
+  // so a doctor that got this far has a readable config. Naming the files is
+  // still best-effort, because it re-reads them a moment after
+  // computeHooksDigest did: a file that vanished in between shows up in the
+  // digest failure and not in this list. When the list comes back empty the
+  // message says that instead of asserting a count of zero unreadable files,
+  // which would read as "nothing is wrong" on the one line that exists to say
+  // otherwise.
+  if (actualDigest === null) {
+    const unreadable = allFiles.filter((file) => {
+      try {
+        readFileSync(join(hooksDir, file));
+        return false;
+      } catch {
+        return true;
+      }
+    });
+    const which = unreadable.length
+      ? `${unreadable.length} hook file(s) unreadable in ${hooksDir} ` +
+        `(e.g. ${unreadable.slice(0, 3).join(', ')})`
+      : `every listed hook file reads back from ${hooksDir} now, so whatever the recompute ` +
+        `could not read has already changed underneath it`;
+    return (
+      `hooksDigest cannot be recomputed. ${which}. Run ` +
+      `${upgradeApplyHint(pluginMode || hypomnemaPluginEnabled)}`
+    );
+  }
+
   const diverged = allFiles.filter((file) => {
     try {
       return !readFileSync(join(hooksDir, file)).equals(readFileSync(join(HOOKS_SRC, file)));
@@ -2329,13 +2756,9 @@ function checkPkgIntegrity(claudeHome) {
     // failed ('registry-unreadable'/'unresolved'), init/upgrade skip the very
     // same write on every re-run until the registry is fixed first (see
     // resolveDurableRoot in init.mjs and the dualSkip branch in upgrade.mjs).
-    const channelJudgmentFailed =
-      hypomnemaPluginEnabled &&
-      (pluginChannel.rootReason === 'registry-unreadable' ||
-        pluginChannel.rootReason === 'unresolved');
     warn(
       'hypo-pkg.json pkgRoot',
-      channelJudgmentFailed
+      channelJudgmentFailed(pluginChannel)
         ? `hypo-pkg.json has no pkgRoot field because the enabled plugin's channel judgment failed ` +
             `(${pluginChannel.rootReason}): re-running /hypo:init or /hypo:upgrade will skip the same ` +
             `write until this resolves. Fix: repair or refresh ~/.claude/plugins/installed_plugins.json ` +
@@ -2451,6 +2874,7 @@ if (rootOk) {
 }
 checkHooks(coreManagedByPlugin);
 checkSettingsJson(coreManagedByPlugin);
+checkDualInstall(pluginChannel);
 checkPkgIntegrity(args.claudeHome);
 checkStaleSibling();
 checkPluginLeafVersion();
@@ -2460,9 +2884,11 @@ if (rootOk) checkExtensions(args.hypoDir, args.claudeHome, 'claude');
 if (rootOk && args.codex) checkExtensions(args.hypoDir, args.claudeHome, 'codex');
 if (rootOk) checkProjectIndexAnchors(args.hypoDir);
 if (rootOk) checkSessionCloseArtifacts(args.hypoDir);
+if (rootOk) checkHalfClosedReceipts(args.hypoDir);
 if (rootOk) checkSyncState(args.hypoDir);
 if (rootOk) checkProjectSuggestions(args.hypoDir);
 if (rootOk) checkProposals(args.hypoDir);
+if (rootOk) checkCloseIntent(args.hypoDir);
 if (rootOk) checkFeedbackProjection(args.hypoDir, args.claudeHome, args.projectId);
 checkGit(args.hypoDir);