hypomnema 1.7.0 → 1.7.2

package/scripts/doctor.mjs

@@ -13,17 +13,26 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { join, relative, extname } from 'path';
+import { join, relative, extname, dirname } from 'path';
 import { homedir } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { readRenameMarker, renameMarkerPath, RENAME_MARKER_REL } from './lib/rename-marker.mjs';
+import { resolveGitHooksDir } from './lib/git-hooks-dir.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import {
   readSyncState,
+  readSyncLastSuccess,
+  classifySyncOp,
   projectSuggestionsPath,
   collectProjectWorkingDirs,
+  detectSessionCloseArtifact,
+  localAndUtcDates,
+  SESSION_CLOSED_MARKER_STALE_MS,
+  isUsablePkgRootLocal,
+  selfLocationPkgRootFrom,
 } from '../hooks/hypo-shared.mjs';
 import { listProposals } from '../hooks/proposal-store.mjs';
 import {
@@ -43,12 +52,19 @@ import {
   CODEX_TYPES,
 } from './lib/extensions.mjs';
 import { sha256, readFileIfRegular, readPkgJson } from './lib/pkg-json.mjs';
+import {
+  provenancePath,
+  EXPECTED_PKG_NAME,
+  HOOKS_DIGEST_FIELD,
+  computeHooksDigest,
+} from './lib/pkg-provenance.mjs';
 import { resolveCliOnPath, classifyInstall } from '../hooks/version-check.mjs';
 import { isHypomnemaPluginEnabled } from './lib/plugin-detect.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..');
+const HOOKS_SRC = join(PKG_ROOT, 'hooks');
 
 // ── install channel ───────────────────────────────────────────────────────────
 //
@@ -313,6 +329,8 @@ function checkHooks(coreManagedByPlugin) {
   } else {
     fail('Hook files installed', `No hook files found in ${claudeHooks} — run /hypo:init`);
   }
+
+  checkProvenanceSidecar(claudeHooks, 'hooks/.hypo-provenance.json');
 }
 
 function checkSettingsJson(coreManagedByPlugin) {
@@ -450,20 +468,168 @@ function checkGit(hypoDir) {
     warn('Git remote origin', 'No remote configured — wiki will not sync/backup automatically');
   }
 
-  const preCommitPath = join(hypoDir, '.git', 'hooks', 'pre-commit');
+  // Ask git for the ACTIVE hooks dir rather than assuming <repo>/.git/hooks —
+  // that guess is wrong in a linked worktree (`.git` is a file) and whenever
+  // core.hooksPath is set, and reporting "not installed" for either would be a
+  // false negative. Read-side policy differs from the installer's: doctor
+  // reports a hooks dir it would refuse to WRITE into, so the user can see it.
+  const resolved = resolveGitHooksDir(hypoDir);
+  if (!resolved.ok) {
+    const detail =
+      resolved.reason === 'hooks-disabled'
+        ? `Hooks path is not a directory (${resolved.path}) — git runs no hooks, so the .hypoignore guard cannot run`
+        : `Could not resolve the git hooks directory (${resolved.detail || resolved.reason})`;
+    warn('git hooks/pre-commit', detail);
+    return;
+  }
+
+  const preCommitPath = join(resolved.path, 'pre-commit');
+  const label = resolved.owned ? 'git hooks/pre-commit' : `pre-commit (${resolved.path})`;
+  let content = null;
+  let unreadable = null;
   if (existsSync(preCommitPath)) {
-    const content = readFileSync(preCommitPath, 'utf-8');
-    if (content.includes('# hypo-managed:pre-commit:start')) {
-      pass('.git/hooks/pre-commit', 'Hypomnema .hypoignore guard installed');
-    } else {
-      warn(
-        '.git/hooks/pre-commit',
-        'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore',
-      );
+    try {
+      content = readFileSync(preCommitPath, 'utf-8');
+    } catch (e) {
+      unreadable = e.code || e.message;
     }
+  }
+
+  if (unreadable) {
+    warn(label, `Exists but could not be read (${unreadable})`);
+  } else if (content === null) {
+    // Telling the user to run /hypo:init here would contradict the ownership
+    // warning below, which says it will refuse this very path.
+    warn(
+      label,
+      resolved.owned
+        ? 'Not installed — run /hypo:init to install .hypoignore guard'
+        : 'Not installed, and /hypo:init will not install into this path — point core.hooksPath back inside the repository, or install the guard yourself',
+    );
+  } else if (content.includes('# hypo-managed:pre-commit:start')) {
+    pass(label, 'Hypomnema .hypoignore guard installed');
   } else {
-    warn('.git/hooks/pre-commit', 'Not installed — run /hypo:init to install .hypoignore guard');
+    warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');
+  }
+
+  // Reported even when the hook above was unreadable — an unreadable hook is
+  // exactly when knowing WHERE git looks matters most.
+  if (!resolved.owned) {
+    warn(
+      'core.hooksPath',
+      `Points outside this repository (${resolved.path}) — /hypo:init will not install there`,
+    );
+  }
+}
+
+// rename.mjs --apply writes .cache/rename-in-progress.json before its first
+// inbound-link rewrite and removes it only after the terminal move lands (see
+// rename.mjs's writeRenameMarker/clearRenameMarker). A marker still present
+// means the process died mid-run: some inbound wikilinks may already point at
+// `to` while the page/directory itself still sits at `from`. checkBrokenLinks
+// below would just report those as generic broken links (W4's doctor
+// counterpart) with no clue why — this names the cause and the exact fix.
+// Re-running the SAME command converges on its own (the module docstring's
+// move-last invariant): nothing to merge or roll back by hand.
+// Best-effort: does this vault's git repo leave `markerPath` un-ignored (either
+// already tracked, or plain untracked-and-stageable)? `git check-ignore` answers
+// both at once — a tracked file is also reported "not ignored" by it, since
+// .gitignore rules don't retroactively apply to tracked paths. Fails CLOSED to
+// "don't know, say nothing": no `.git`, no git on PATH, or any non-0/1 exit
+// (128 = not a repo / path outside it / other error) all return false, because
+// this is advisory-only and a wrong guess is worse than silence (codex CONCERN 3
+// — never turn an inconclusive git query into an error of its own).
+function markerNotGitIgnored(hypoDir, markerPath) {
+  if (!existsSync(join(hypoDir, '.git'))) return false;
+  const rel = relative(hypoDir, markerPath);
+  const r = spawnSync('git', ['-C', hypoDir, 'check-ignore', '-q', rel], { encoding: 'utf-8' });
+  if (r.error || r.status === null) return false;
+  if (r.status !== 0 && r.status !== 1) return false; // 128 etc — inconclusive
+  return r.status === 1; // check-ignore's "not ignored" exit code
+}
+
+function checkIncompleteRename(hypoDir) {
+  // "no marker" and "a marker we cannot read" are different answers and must not
+  // collapse. readRenameMarker returns null for both, so ask the filesystem
+  // which one it is: a present-but-unreadable marker still means a rename did
+  // not finish, and reporting that as a pass would make the detector fail open
+  // on exactly the case it exists for.
+  const markerPath = renameMarkerPath(hypoDir);
+  const present = existsSync(markerPath);
+  if (!present) {
+    pass('Incomplete rename', 'No rename-in-progress marker found');
+    return;
+  }
+
+  // codex CONCERN 3: a legacy/custom vault whose .gitignore predates
+  // templates/gitignore's `.cache/` entry (init never edits an existing
+  // .gitignore) can let `git add -A` commit this marker, producing a ghost
+  // warning on another machine that never ran a rename at all. Advisory only —
+  // never turns the rename itself into an error — appended to every branch
+  // below that reports on a present marker.
+  const gitAdvisory = markerNotGitIgnored(hypoDir, markerPath)
+    ? ` This vault's git repo does not ignore ${dirname(RENAME_MARKER_REL)}/ — \`git add -A\` could commit this marker and produce a ghost warning on another machine. Add \`.cache/\` to .gitignore.`
+    : '';
+
+  const marker = readRenameMarker(hypoDir);
+  if (!marker || !marker.from || !marker.to) {
+    warn(
+      'Incomplete rename',
+      `${markerPath} exists but is unreadable or missing its from/to fields, so a rename did not finish and this cannot say which one. Inspect the file, re-run that rename to converge, then delete the marker.${gitAdvisory}`,
+    );
+    return;
+  }
+
+  // codex BLOCKER 2: the marker alone cannot distinguish a genuinely stuck
+  // rename from one that finished right before the process died — rename.mjs's
+  // move (renameSync) is the terminal step, and the marker is only cleared
+  // AFTER it. Cross-check `from`/`to` (vault-root-relative) against the
+  // filesystem to tell the three reachable states apart.
+  const { mode, from, to, started_at } = marker;
+  const label = mode === 'directory' ? 'directory' : 'page';
+  const fromExists = existsSync(join(hypoDir, from));
+  const toExists = existsSync(join(hypoDir, to));
+  const cmd = `node ${join(PKG_ROOT, 'scripts', 'rename.mjs')} --hypo-dir=${hypoDir} --from=${from} --to=${to} --apply`;
+
+  if (fromExists && !toExists) {
+    // The real in-progress case: --from still resolves, so re-running the
+    // IDENTICAL command converges on its own (rename.mjs's move-last invariant).
+    warn(
+      'Incomplete rename',
+      `a ${label} rename from '${from}' to '${to}' did not finish` +
+        (started_at ? ` (started ${started_at})` : '') +
+        ` — some inbound links may already point at the new name while the ${label} itself has not moved. Re-run the identical rename to converge: ${cmd}${gitAdvisory}`,
+    );
+    return;
+  }
+
+  if (!fromExists && toExists) {
+    // The move already landed — renameSync is one syscall, so this can only mean
+    // the process died AFTER it and BEFORE clearRenameMarker ran. Re-running the
+    // same command here would just fail (`--from` no longer resolves — see
+    // rename.mjs's own "did not resolve to a unique existing page" refusal), so
+    // suggesting a re-run (the prior behavior) handed the user a command that
+    // errors. Nothing to converge: the marker is pure leftover.
+    warn(
+      'Incomplete rename',
+      `a ${label} rename from '${from}' to '${to}' already finished (the ${label} moved) but its ` +
+        `in-progress marker was never cleared — the process likely died right after the move landed. ` +
+        `Nothing left to redo; just delete the stale marker: rm ${markerPath}${gitAdvisory}`,
+    );
+    return;
   }
+
+  // Both paths exist, or neither does — the marker's from/to no longer map onto
+  // a determinable state (e.g. something else since recreated one of the two
+  // paths). Refuse to guess in either direction; a human needs to look.
+  warn(
+    'Incomplete rename',
+    `${markerPath} names a ${label} rename from '${from}' to '${to}', but ${
+      fromExists && toExists
+        ? 'BOTH the from and to paths currently exist'
+        : 'NEITHER the from nor the to path currently exists'
+    } — cannot tell whether the rename finished. Inspect both paths by hand, then either re-run the rename or delete the marker: ${markerPath}${gitAdvisory}`,
+  );
 }
 
 function checkBrokenLinks(hypoDir, ignorePatterns = []) {
@@ -644,6 +810,237 @@ function checkProjectIndexAnchors(hypoDir) {
   }
 }
 
+// The project(s) a commit touched, by which projects/<slug>/ paths it
+// changed — a SET, because a merge or a multi-project commit can touch more
+// than one, and `close the session` in that commit's message must then be
+// verified against ALL of them, not silently attributed to just one.
+// Empty when the commit touches no project path, or `git show` itself fails
+// (a corrupt or unreachable object) — both are "can't determine scope", which
+// this returns as *no scope at all*, not "any scope"; see markerCoversArtifact
+// for why that direction matters.
+function deriveCommitProjects(hypoDir, hash) {
+  // --name-status -M (not --name-only): a rename prints ONLY the destination
+  // path under --name-only ("R100 old\tnew" collapses to just "new"), so a
+  // projects/a/hot.md → projects/b/hot.md rename would silently drop project
+  // a from scope — a marker naming only "b" would then wrongly cover the
+  // whole commit. -M's tab-separated `status\told\tnew` line carries both.
+  const show = spawnSync('git', ['-C', hypoDir, 'show', '--name-status', '-M', '--format=', hash], {
+    encoding: 'utf-8',
+  });
+  if (show.status !== 0 || !show.stdout) return [];
+  const projects = new Set();
+  for (const line of show.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    // status\tpath (add/modify/delete) or status\told\tnew (rename/copy) —
+    // every field after the status column is a path this commit touched.
+    const [, ...paths] = line.split('\t');
+    for (const path of paths) {
+      const m = /^projects\/([^/]+)\//.exec(path.trim());
+      // _template is the scaffold, never a real project — same exclusion the
+      // file-scan loop above applies, so a commit that happens to touch it
+      // (e.g. an init/upgrade run) doesn't manufacture a phantom project a
+      // marker can never cover.
+      if (m && m[1] !== '_template') projects.add(m[1]);
+    }
+  }
+  return [...projects];
+}
+
+// A marker only vouches for the project(s) it names, PLUS its own calendar
+// day. Two ways that can go wrong if handled loosely, both fixed here:
+//
+//   1. Scope creep: a same-day close in a DIFFERENT project must not silence
+//      this one (the marker was introduced for per-session precision
+//      specifically to prevent one close from vouching for another —
+//      hooks/hypo-shared.mjs SESSION_CLOSED_MARKER_STALE_MS comment).
+//   2. Timezone artifact: closed_at is UTC; a file-content artifact's date is
+//      local (hooks/hypo-shared.mjs localAndUtcDates() accepts both for
+//      exactly this reason).
+//
+// `artifact.scope.kind` is a closed set, not a free-form nullable project —
+// an UNKNOWN scope must never default to "any marker on that date covers
+// it": this is a warning-only, best-effort check, so the cost of a false
+// PASS (the exact failure mode it exists to catch) outweighs the cost of a
+// false WARN (mild noise). Concretely:
+//   • 'root-universal' — root hot.md. The real close procedure updates it on
+//     EVERY close regardless of project (closeFileTargets in
+//     hooks/hypo-shared.mjs), so date-only correlation is legitimate here,
+//     not a gap.
+//   • 'unscoped' — root session-state.md (NOT part of the real close file
+//     set — the same closeFileTargets list proves it), or a commit whose
+//     touched-project set came back empty/ambiguous. No marker can vouch for
+//     an artifact with no verifiable scope, so this never matches, ever.
+//   • 'projects' — a project file, or a commit that touched one or more
+//     identifiable projects/<slug>/ paths. EVERY named project must appear
+//     in the marker's own `projects` list.
+function markerCoversArtifact(marker, artifact) {
+  if (!marker.dates.includes(artifact.date)) return false;
+  switch (artifact.scope.kind) {
+    case 'root-universal':
+      return true;
+    case 'projects':
+      return artifact.scope.projects.every((p) => marker.projects.includes(p));
+    default:
+      return false; // 'unscoped'
+  }
+}
+
+// Post-hoc surface for a session closed BY HAND, without the session-closed
+// marker hard gate ever firing (the gate lives on the marker writer, and a
+// close done by editing files directly never calls it). Warning-only: this
+// cannot tell an actually-approved-but-ungated close from an over-close, it
+// can only say the two signals disagree, so it never blocks.
+//
+// Window: 7 days for the git-log scan, matching SESSION_CLOSED_MARKER_STALE_MS
+// in hooks/hypo-shared.mjs — a marker older than that is already treated as
+// expired everywhere else (enforced below too, when reading the raw marker
+// files), so correlating against a longer window would compare a close
+// artifact against a marker doctor itself considers stale.
+function checkSessionCloseArtifacts(hypoDir) {
+  const artifacts = [];
+
+  const scanFile = (path, scope) => {
+    if (!existsSync(path)) return;
+    let content;
+    try {
+      content = readFileSync(path, 'utf-8');
+    } catch {
+      return;
+    }
+    const result = detectSessionCloseArtifact({ path, content });
+    if (result.matched) {
+      artifacts.push({ date: result.date, scope, where: relative(hypoDir, path) });
+    }
+  };
+
+  // Root hot.md is a real close artifact of every close, project or not — see
+  // markerCoversArtifact's 'root-universal' case. Root session-state.md is
+  // NOT: the real close procedure never touches it (closeFileTargets in
+  // hooks/hypo-shared.mjs lists hot.md/log.md + the ACTIVE project's files
+  // only), so a 마감 heading appearing there has no legitimate close to
+  // attribute it to — 'unscoped' means no marker, however fresh, ever covers it.
+  scanFile(join(hypoDir, 'hot.md'), { kind: 'root-universal' });
+  scanFile(join(hypoDir, 'session-state.md'), { kind: 'unscoped' });
+  const projectsDir = join(hypoDir, 'projects');
+  if (existsSync(projectsDir)) {
+    for (const slug of readdirSync(projectsDir)) {
+      if (slug === '_template') continue;
+      const dir = join(projectsDir, slug);
+      try {
+        if (!statSync(dir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      scanFile(join(dir, 'session-state.md'), { kind: 'projects', projects: [slug] });
+      scanFile(join(dir, 'hot.md'), { kind: 'projects', projects: [slug] });
+    }
+  }
+
+  if (existsSync(join(hypoDir, '.git'))) {
+    const log = spawnSync(
+      'git',
+      ['-C', hypoDir, 'log', '--since=7.days.ago', '--format=%H%x1f%ad%x1f%s', '--date=short'],
+      { encoding: 'utf-8' },
+    );
+    if (log.status === 0 && log.stdout) {
+      for (const line of log.stdout.split('\n')) {
+        if (!line.trim()) continue;
+        const [hash, date, subject] = line.split('\x1f');
+        if (detectSessionCloseArtifact({ commitMessage: subject }).matched) {
+          const projects = deriveCommitProjects(hypoDir, hash);
+          artifacts.push({
+            date,
+            scope: projects.length > 0 ? { kind: 'projects', projects } : { kind: 'unscoped' },
+            where: `commit "${subject}"`,
+          });
+        }
+      }
+    }
+  }
+
+  if (artifacts.length === 0) {
+    pass('Session-close artifacts', 'No close artifacts found');
+    return;
+  }
+
+  // Read the raw marker files directly rather than readSessionClosedMarker,
+  // which also DELETES an expired one as a side effect; a health check
+  // should not mutate state to produce a diagnosis. Staleness is still
+  // enforced here (same SESSION_CLOSED_MARKER_STALE_MS window) so an
+  // already-expired marker can't vouch for anything.
+  const cacheDir = join(hypoDir, '.cache');
+  const markers = [];
+  let cacheEntries = [];
+  if (existsSync(cacheDir)) {
+    try {
+      cacheEntries = readdirSync(cacheDir);
+    } catch {
+      // unreadable .cache/ — not this check's job to diagnose that
+    }
+  }
+  for (const file of cacheEntries) {
+    if (!file.startsWith('session-closed-') || !file.endsWith('.marker')) continue;
+    try {
+      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;
+      // 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
+      // runtime scope resolver already refuses to trust it uncorroborated,
+      // and doctor has no corroborating signal of its own to add, so it
+      // must refuse it too rather than re-opening the same hole standalone.
+      const projects = Array.isArray(data?.projects) ? data.projects.filter(Boolean) : [];
+      markers.push({ projects: [...new Set(projects)], dates: localAndUtcDates(new Date(ts)) });
+    } catch {
+      // corrupt marker — not this check's job to clean up
+    }
+  }
+
+  const unmatched = artifacts.filter(
+    (a) => !a.date || !markers.some((m) => markerCoversArtifact(m, a)),
+  );
+  if (unmatched.length === 0) {
+    pass(
+      'Session-close artifacts',
+      `${artifacts.length} close artifact(s), all covered by a session-closed marker`,
+    );
+    return;
+  }
+
+  const sample = unmatched
+    .slice(0, 5)
+    .map((a) => `${a.where}${a.date ? ` (${a.date})` : ''}`)
+    .join(', ');
+  const extra = unmatched.length > 5 ? ` (+${unmatched.length - 5} more)` : '';
+  // 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
+  // are worth a human look, so the wording covers both instead of asserting
+  // the stronger, sometimes-wrong one.
+  warn(
+    '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}`,
+  );
+}
+
+/**
+ * Render a `.cache/sync-last-success.json` record as an absolute-time note.
+ * Deliberately no "recent"/staleness verdict — the failure-state check above
+ * already carries the health signal; this only says what and when.
+ */
+function formatLastSuccess(lastSuccess) {
+  const pull = lastSuccess.pull
+    ? `pull ${lastSuccess.pull.timestamp} (${lastSuccess.pull.host})`
+    : 'pull: none recorded';
+  const push = lastSuccess.push
+    ? `push ${lastSuccess.push.timestamp} (${lastSuccess.push.host})`
+    : 'push: none recorded';
+  return `${pull}; ${push}`;
+}
+
 function checkSyncState(hypoDir) {
   // "open" = file exists with ≥1 entries; session-start clears once
   // sync is healthy again. Schema + parsing live in hooks/hypo-shared.mjs.
@@ -655,20 +1052,96 @@ function checkSyncState(hypoDir) {
   }
 
   if (entries.length === 0) {
-    pass('Sync state', 'No unresolved sync failures');
+    // No unresolved failure — but that alone does not mean sync ever ran.
+    // Read the separate, additive last-success record to tell "never synced"
+    // apart from "healthy" and, when present, from a pull-only/push-only
+    // history. A corrupt success file warns rather than crashing, same as the
+    // sync-state parse-error handling above.
+    const { data: lastSuccess, parseError: successParseError } = readSyncLastSuccess(hypoDir);
+    if (successParseError) {
+      warn('Sync state', 'Cannot parse .cache/sync-last-success.json — inspect manually');
+    } else if (!lastSuccess.pull && !lastSuccess.push) {
+      pass(
+        'Sync state',
+        'No unresolved sync failures — never synced (no recorded pull or push yet)',
+      );
+    } else {
+      // Distinguishes pull-only / push-only / both, since formatLastSuccess
+      // reports "none recorded" for whichever op is absent.
+      pass(
+        'Sync state',
+        `No unresolved sync failures. Last success — ${formatLastSuccess(lastSuccess)}`,
+      );
+    }
   } else {
     const last = entries[entries.length - 1];
-    // A merge conflict needs a real manual merge, not a plain push/pull — give
-    // the same explicit guidance session-start does instead of the generic hint.
-    if (String(last.op || '').startsWith('conflict')) {
+    // An unresolved failure does not mean the OTHER operation never
+    // succeeded — a push failure can sit right next to a healthy pull, and
+    // the last-success record above used to only wire into the healthy/
+    // never-synced branch, leaving this branch silent about it. Append it
+    // here too, best-effort, same as the healthy branch — a corrupt success
+    // file still warns, never crashes.
+    const { data: lastSuccess, parseError: successParseError } = readSyncLastSuccess(hypoDir);
+    // Not "unreadable": readSyncLastSuccess also sets parseError for a file
+    // that reads fine and parses as valid JSON but has the wrong shape (a
+    // malformed pull/push field, or an unrecognized key) — "unreadable" would
+    // misdescribe that case.
+    const successSuffix = successParseError
+      ? ' (.cache/sync-last-success.json is invalid or unreadable — inspect manually)'
+      : lastSuccess.pull || lastSuccess.push
+        ? ` Last success — ${formatLastSuccess(lastSuccess)}.`
+        : '';
+    // More than one open entry means the vault has been failing across
+    // multiple sync attempts without clearing — name each one (op@timestamp),
+    // not just the last, so the user isn't left to open sync-state.json
+    // themselves to see the pattern. Capped like checkBrokenLinks/checkVerifyBy.
+    const unresolvedList =
+      entries.length > 1
+        ? ` Unresolved: ${entries
+            .slice(-5)
+            .map((e) => `${e.op || '?'}@${e.timestamp || '?'}`)
+            .join(', ')}${entries.length > 5 ? ` (+${entries.length - 5} more)` : ''}.`
+        : '';
+    // classifySyncOp (hooks/hypo-shared.mjs) is the single judgment both this
+    // check and hypo-session-start.mjs's syncStateNotice branch on, so the
+    // two surfaces cannot silently diverge on WHICH op gets which treatment.
+    // 'conflict-unresolved' — the merge --abort itself failed — is the more
+    // dangerous of the two conflict ops: the tree may still be
+    // half-merged (unmerged index entries, or an in-progress MERGE_HEAD), so
+    // it gets dedicated guidance rather than the plain-conflict branch below,
+    // which claims "your local work is committed" (not true when the abort
+    // itself failed) and advises `git pull --no-rebase` (git would simply
+    // refuse that mid-merge). Wording mirrors hypo-session-start.mjs's
+    // syncStateNotice so the two surfaces never contradict each other.
+    const cls = classifySyncOp(last.op);
+    if (cls === 'conflict-unresolved') {
       warn(
         'Sync state',
-        `${entries.length} unresolved sync issue(s) — last: remote diverged (merge conflict). Your local work is committed; the other machine's version is on the remote. Resolve with \`git pull --no-rebase\`, fix conflicts, then push.`,
+        `${entries.length} unresolved sync issue(s) — last: remote diverged AND the automatic merge-abort failed; the working tree may still be half-merged (unmerged paths or an in-progress merge). Do NOT commit or push yet. Run \`git status\` first: if a merge is in progress, resolve the conflicts, then \`git add <resolved paths>\` and \`git commit\` (git refuses a commit while unmerged entries remain staged) — or run \`git merge --abort\` to discard it instead, before continuing.${unresolvedList}${successSuffix}`,
+      );
+    } else if (cls === 'conflict') {
+      // A merge conflict needs a real manual merge, not a plain push/pull —
+      // give the same explicit guidance session-start does instead of the
+      // generic hint. This branch is unmerged-index-free by construction (the
+      // abort succeeded), so "committed and safe" is an accurate claim here.
+      warn(
+        'Sync state',
+        `${entries.length} unresolved sync issue(s) — last: remote diverged (merge conflict). Your local work is committed; the other machine's version is on the remote. Resolve with \`git pull --no-rebase\`, fix conflicts, \`git add\` them, then commit and push.${unresolvedList}${successSuffix}`,
+      );
+    } else if (cls === 'unknown-conflict') {
+      // An unrecognized `conflict*` op — a future syncRemote failure mode
+      // this check has no dedicated branch for. Neither the 'conflict'
+      // branch's "committed" claim nor the 'conflict-unresolved' branch's
+      // "abort failed" claim is known to hold here, so assert neither:
+      // report the state as unknown and treat it as unresolved.
+      warn(
+        'Sync state',
+        `${entries.length} unresolved sync issue(s) — last: remote diverged — an unrecognized conflict-related sync failure ('${last.op}') was recorded. Its resolution state cannot be confirmed automatically — treat it as unresolved. Run \`git status\` first to check for unmerged paths or an in-progress merge before committing or pushing.${unresolvedList}${successSuffix}`,
       );
     } else {
       warn(
         'Sync state',
-        `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.`,
+        `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.${unresolvedList}${successSuffix}`,
       );
     }
   }
@@ -766,6 +1239,8 @@ function checkCodexPaths() {
     );
   }
 
+  checkProvenanceSidecar(codexHooks, 'Codex hooks/.hypo-provenance.json');
+
   const settingsPath = join(HOME, '.codex', 'settings.json');
   if (!existsSync(settingsPath)) {
     warn(
@@ -1364,6 +1839,139 @@ function checkStaleSibling() {
   }
 }
 
+// ── provenance sidecar (manual/npm channel) ────────────────────────────────────
+//
+// `.hypo-provenance.json` lives next to a standalone-copied hooks/ dir
+// (installHooks/applyHookFiles — scripts/lib/pkg-provenance.mjs) and is what
+// hooks/hypo-shared.mjs's resolvePkgRoot() falls back to when self-location
+// can't resolve. Absent is a normal state whenever there is no INSTALLED
+// hooks/hypo-shared.mjs at `hooksDir` to worry about at all (plugin channel:
+// hooks run straight from CLAUDE_PLUGIN_ROOT, nothing is ever copied here;
+// a truly fresh, never-inited home) — that case stays silent. It is also
+// normal, and stays silent, when hypo-shared.mjs IS installed here but
+// self-locates on its own (a dev checkout whose "hooksDir" happens to be the
+// package's own hooks/, not a copy). The one PRESENT-but-broken and the one
+// ABSENT-but-should-not-be-silent case are both actionable (CONCERN 4):
+//   - present sidecar that fails to verify → WARN, same three-way shape as
+//     checkPkgIntegrity below, never FAIL (a broken sidecar just degrades
+//     PKG_ROOT to null, surfaced live by hypo-session-start.mjs's
+//     PKG_ROOT-null banner, not corrupting anything on disk)
+//   - installed hypo-shared.mjs, self-location fails for it, AND no sidecar
+//     at all → that combination IS "PKG_ROOT is null for every hook running
+//     from here" (resolvePkgRoot() has nothing left to try), so silence here
+//     would hide exactly the state the live banner already warns about
+function checkProvenanceSidecar(hooksDir, label) {
+  const sidecarPath = provenancePath(hooksDir);
+  if (!existsSync(sidecarPath)) {
+    if (existsSync(join(hooksDir, 'hypo-shared.mjs')) && !selfLocationPkgRootFrom(hooksDir)) {
+      warn(
+        label,
+        `no provenance sidecar, and this install's hooks cannot self-locate their ` +
+          `package — PKG_ROOT resolves to null for every hook running from ${hooksDir}; ` +
+          `run \`hypomnema upgrade --apply\` to write one`,
+      );
+    }
+    return;
+  }
+
+  let sidecar;
+  try {
+    sidecar = JSON.parse(readFileSync(sidecarPath, 'utf-8'));
+  } catch {
+    warn(
+      label,
+      `${sidecarPath} is not valid JSON — run \`hypomnema upgrade --apply\` to rewrite it`,
+    );
+    return;
+  }
+
+  const { pkgRoot, hypoSharedSha256, [HOOKS_DIGEST_FIELD]: hooksDigest } = sidecar || {};
+
+  // Same predicate the runtime resolver requires (isUsablePkgRootLocal, used
+  // by readVerifiedProvenancePkgRoot in hooks/hypo-shared.mjs) — imported,
+  // not hand-rolled again here, so a version-less "name":"hypomnema" root can
+  // no longer PASS this check while resolvePkgRoot() treats it as null.
+  const usableOk = isUsablePkgRootLocal(pkgRoot);
+
+  let producerName = null;
+  try {
+    producerName = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).name;
+  } catch {
+    /* pkgRoot missing/unreadable — nameOk stays false below */
+  }
+  const nameOk = producerName === EXPECTED_PKG_NAME;
+
+  let hashOk = false;
+  try {
+    hashOk = sha256(readFileSync(join(hooksDir, 'hypo-shared.mjs'))) === hypoSharedSha256;
+  } catch {
+    /* hooks/hypo-shared.mjs unreadable in its own hooks dir — hashOk stays false */
+  }
+
+  if (usableOk && nameOk && hashOk) {
+    // hooksDigest (BLOCKER A item 3) can still turn this into a warn: it is
+    // folded into the SAME label/check rather than pushed as a second entry,
+    // so a caller reading checks by label (every other check in this file,
+    // and every test asserting on one) sees exactly one verdict per sidecar.
+    const digestIssue = hooksDigestMismatch(hooksDir, hooksDigest);
+    if (!digestIssue) {
+      pass(label, `verified — resolves to ${pkgRoot}`);
+    } else {
+      warn(label, `verified (pkgRoot/hash), but ${digestIssue}`);
+    }
+    return;
+  }
+  const reasons = [];
+  if (!usableOk) {
+    reasons.push(
+      `recorded pkgRoot (${pkgRoot}) is not a usable package root (must be an absolute ` +
+        `path to a directory whose package.json carries a version)`,
+    );
+  }
+  if (!nameOk) reasons.push(`recorded pkgRoot (${pkgRoot}) is not this package`);
+  if (!hashOk)
+    reasons.push('recorded hypoSharedSha256 does not match the installed hypo-shared.mjs');
+  warn(
+    label,
+    `${sidecarPath} does not verify (${reasons.join('; ')}) — resolvePkgRoot() will treat ` +
+      `PKG_ROOT as unresolved this session; run \`hypomnema upgrade --apply\` to refresh it`,
+  );
+}
+
+// BLOCKER A item 3: the runtime SHA check above (hashOk) pins ONE file,
+// hypo-shared.mjs — see that function's own hooks/hypo-shared.mjs-side
+// comment for why. This pins every OTHER file hooks.json wires up too, once
+// per `hypomnema doctor` run rather than once per hook load (too expensive
+// to do there — see computeHooksDigest's doc comment in
+// scripts/lib/pkg-provenance.mjs). Skips silently when the sidecar predates
+// this field (an older init/upgrade wrote it before BLOCKER A existed) —
+// there is nothing recorded to compare against, and the runtime never reads
+// this field either, so staying quiet hides nothing the runtime already
+// 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.
+function hooksDigestMismatch(hooksDir, recordedDigest) {
+  if (typeof recordedDigest !== 'string' || !recordedDigest) return null;
+  const actualDigest = computeHooksDigest(PKG_ROOT, hooksDir);
+  if (actualDigest === null || actualDigest === recordedDigest) return null;
+
+  const allFiles = [...Object.values(HOOK_MAP).flat(), ...SHARED_FILES];
+  const diverged = allFiles.filter((file) => {
+    try {
+      return !readFileSync(join(hooksDir, file)).equals(readFileSync(join(HOOKS_SRC, file)));
+    } catch {
+      return true; // unreadable on either side counts as diverged
+    }
+  });
+  const examples = diverged.slice(0, 3).join(', ');
+  return (
+    `hooksDigest mismatch: ${diverged.length}/${allFiles.length} hook file(s) differ from ` +
+    `the current package source${examples ? ` (e.g. ${examples})` : ''} — run ` +
+    `\`hypomnema upgrade --apply\``
+  );
+}
+
 // ── package integrity ─────────────────────────────────────────────────────────
 //
 // ~/.claude/hypo-pkg.json is a snapshot written once by init/upgrade and never
@@ -1491,6 +2099,7 @@ if (rootOk) {
   checkFiles(args.hypoDir);
   checkScanIgnoreFile(args.hypoDir);
   checkBrokenLinks(args.hypoDir, ignorePatterns);
+  checkIncompleteRename(args.hypoDir);
   checkVerifyBy(args.hypoDir, ignorePatterns);
 }
 checkHooks(coreManagedByPlugin);
@@ -1501,6 +2110,7 @@ if (args.codex) checkCodexPaths();
 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) checkSyncState(args.hypoDir);
 if (rootOk) checkProjectSuggestions(args.hypoDir);
 if (rootOk) checkProposals(args.hypoDir);