hypomnema 1.6.2 → 1.7.1

package/scripts/lib/git-hooks-dir.mjs

@@ -0,0 +1,229 @@
+/**
+ * Resolve a repository's active git hooks directory by asking git, never by
+ * assuming the on-disk layout.
+ *
+ * The layout assumption this replaces (`join(root, '.git', 'hooks')`) is wrong
+ * in two ways that both showed up in practice:
+ *
+ *   1. In a linked worktree `.git` is a regular FILE holding `gitdir: <path>`,
+ *      so `existsSync` passes and `mkdirSync` dies with ENOTDIR.
+ *   2. When `core.hooksPath` is set, git does not read `.git/hooks` at all, so
+ *      a hook written there is inert.
+ *
+ * `git rev-parse --git-path hooks` handles both: it follows the worktree's
+ * gitdir pointer AND substitutes `core.hooksPath` (verified on git 2.50.1 —
+ * `/dev/null` stays `/dev/null`, a relative value stays relative, and `~` is
+ * expanded). That makes rev-parse the single authority here; reading
+ * `core.hooksPath` out of the config ourselves would be strictly worse, since
+ * it would leave `~` unexpanded and could not tell an empty-but-set value from
+ * an unset one.
+ *
+ * Two things rev-parse does NOT give us, so we add them:
+ *
+ *   - `git -C <root>` does not neutralize ambient git environment variables.
+ *     `GIT_DIR` + `GIT_WORK_TREE` redirect the probe at a foreign repository,
+ *     and `GIT_CONFIG_COUNT`/`GIT_CONFIG_PARAMETERS` redirect it at an
+ *     arbitrary hooks path. Every probe therefore runs under a scrubbed env,
+ *     with the scrub list taken from git's own `--local-env-vars` when
+ *     available.
+ *   - `core.hooksPath` may point at a directory SHARED by many repositories
+ *     (the documented centralized-hooks pattern). Auto-installing there would
+ *     put our hook in front of unrelated repositories' commits, and our
+ *     post-commit executes `$REPO_ROOT/scripts/upgrade.mjs` dynamically. So the
+ *     result carries an `owned` flag, and callers that WRITE must refuse when
+ *     it is false. Callers that only READ (doctor) may report the path.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, lstatSync, realpathSync, statSync } from 'fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'path';
+
+// Fallback scrub list for git versions without `rev-parse --local-env-vars`.
+// Mirrors scripts/install-git-hooks.mjs, which established this trust model.
+const STATIC_LOCAL_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_CONFIG',
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_PREFIX',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_SHALLOW_FILE',
+];
+
+function buildScrubbedEnv(localEnvList) {
+  const scrub = new Set([
+    ...(localEnvList || STATIC_LOCAL_ENV_VARS),
+    'GIT_NAMESPACE',
+    'GIT_CEILING_DIRECTORIES',
+    // GIT_CONFIG_COUNT / GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n inject config
+    // wholesale and are not always listed by --local-env-vars.
+    ...Object.keys(process.env).filter((k) => /^GIT_CONFIG_/.test(k)),
+  ]);
+  return Object.fromEntries(Object.entries(process.env).filter(([k]) => !scrub.has(k)));
+}
+
+// Canonicalize a path that may not exist yet: realpath the deepest existing
+// ancestor and re-append the rest. Without this, a hooks dir git will create
+// lazily could evade the containment check via an unresolved symlinked parent.
+function canonicalize(p) {
+  let cur = resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      return join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(p); // hit the root; nothing to resolve
+      // basename, not a slice: when the parent IS the root it already ends in a
+      // separator, so `parent.length + 1` would eat the first real character
+      // ("/Nope/x" -> "ope/x") and could rewrite an external path into one that
+      // looks repository-owned.
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function isInside(child, parent) {
+  return child === parent || child.startsWith(parent + sep);
+}
+
+/**
+ * @param {string} repoRoot        working tree root to probe
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {{ok: true, path: string, owned: boolean, gitDir: string, commonDir: string}
+ *          |{ok: false, reason: string, detail?: string, path?: string}}
+ *
+ * Failure reasons are deliberately distinct so callers can react differently:
+ *   not-a-repo        no `.git` entry (also the case for a bare repo — matches
+ *                     the pre-existing behavior of every call site)
+ *   git-unavailable   git is not on PATH / not executable
+ *   probe-failed      git ran but could not resolve the repo (stale `.git`
+ *                     pointer, dubious ownership, timeout, ...)
+ *   hooks-disabled    the active hooks path is `/dev/null` or an existing
+ *                     non-directory — git's documented way to disable hooks
+ */
+export function resolveGitHooksDir(repoRoot, { timeoutMs = 5000 } = {}) {
+  if (!existsSync(join(repoRoot, '.git'))) return { ok: false, reason: 'not-a-repo' };
+
+  let env = buildScrubbedEnv(null);
+  const run = (args) =>
+    execFileSync('git', args, {
+      encoding: 'utf-8',
+      env,
+      cwd: repoRoot,
+      timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 1024 * 1024,
+    }).trim();
+
+  try {
+    // Enrich the scrub list from git's own truth when this git supports it.
+    try {
+      env = buildScrubbedEnv(run(['rev-parse', '--local-env-vars']).split(/\r?\n/).filter(Boolean));
+    } catch {
+      // Old git without --local-env-vars; the static list already applied.
+    }
+
+    const gitDir = canonicalize(run(['rev-parse', '--absolute-git-dir']));
+    const rawCommon = run(['rev-parse', '--git-common-dir']);
+    // A relative --git-common-dir is relative to the command's cwd, which we
+    // pinned to repoRoot.
+    const commonDir = canonicalize(isAbsolute(rawCommon) ? rawCommon : join(repoRoot, rawCommon));
+    const topLevel = canonicalize(run(['rev-parse', '--show-toplevel']));
+
+    // --path-format is git 2.31+. Fall back to the plain form, whose output is
+    // relative to cwd (= repoRoot) when core.hooksPath is relative.
+    let raw;
+    try {
+      raw = run(['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+    } catch {
+      raw = run(['rev-parse', '--git-path', 'hooks']);
+    }
+    if (!raw) return { ok: false, reason: 'probe-failed', detail: 'empty hooks path' };
+
+    const hooksPath = canonicalize(isAbsolute(raw) ? raw : join(repoRoot, raw));
+
+    // git documents core.hooksPath=/dev/null as "disable all hooks". Treat any
+    // existing non-directory the same way rather than failing on mkdir later.
+    if (existsSync(hooksPath) && !statSync(hooksPath).isDirectory()) {
+      return { ok: false, reason: 'hooks-disabled', path: hooksPath };
+    }
+
+    // Repository-owned means: inside this repo's git directory (the normal
+    // `.git/hooks`, and in a linked worktree the shared common dir) or inside
+    // the working tree itself (the `core.hooksPath=.githooks` convention).
+    // Anything else is a location we do not own and must not write into.
+    const owned =
+      isInside(hooksPath, commonDir) ||
+      isInside(hooksPath, gitDir) ||
+      isInside(hooksPath, topLevel);
+
+    return { ok: true, path: hooksPath, owned, gitDir, commonDir };
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: false, reason: 'git-unavailable' };
+    return { ok: false, reason: 'probe-failed', detail: e && (e.code || e.message) };
+  }
+}
+
+/**
+ * Guard the final hook ENTRY, not just the directory it lives in.
+ *
+ * An owned hooks directory can still contain a symlink pointing anywhere, and
+ * `writeFileSync` follows symlinks. Three ways that escapes the boundary the
+ * directory check appears to establish:
+ *   - a live symlink to an external file gets its TARGET overwritten;
+ *   - if that target happens to carry our managed marker, it is rewritten even
+ *     without --force-commands;
+ *   - a DANGLING symlink reads as absent through `existsSync`, so the "not
+ *     installed yet" path creates the external target outright.
+ * So refuse to write through any symlink, and refuse anything that is not a
+ * regular file. Callers log the reason and move on.
+ *
+ * @returns {null | string} null when writing is safe, else a reason to log
+ */
+export function unsafeHookTargetReason(hookPath) {
+  let st;
+  try {
+    st = lstatSync(hookPath);
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null; // genuinely absent — safe to create
+    return `cannot stat (${e.code || e.message})`;
+  }
+  if (st.isSymbolicLink()) return 'is a symlink — refusing to write through it';
+  if (!st.isFile()) return 'exists but is not a regular file';
+  return null;
+}
+
+/**
+ * Write-side wrapper: the hooks directory only if it is safe to install into.
+ * Returns `{dir}` when installing is allowed, otherwise `{skip}` carrying a
+ * human-readable reason for the caller to log.
+ */
+export function hooksDirForInstall(repoRoot, opts) {
+  const r = resolveGitHooksDir(repoRoot, opts);
+  if (!r.ok) {
+    if (r.reason === 'not-a-repo') return { skip: null }; // silent, as before
+    if (r.reason === 'hooks-disabled') {
+      // Do not name core.hooksPath here: the same branch fires for a plain
+      // .git/hooks that happens to be a regular file, where no such setting
+      // exists and naming it would send the user hunting for a phantom config.
+      return { skip: `hooks path is not a directory, so git runs no hooks (${r.path})` };
+    }
+    if (r.reason === 'git-unavailable') return { skip: 'git not available on PATH' };
+    return { skip: `could not resolve hooks dir (${r.detail || r.reason})` };
+  }
+  if (!r.owned) {
+    return {
+      skip: `core.hooksPath points outside this repository (${r.path}) — refusing to install into a shared hooks directory`,
+    };
+  }
+  return { dir: r.path };
+}

package/scripts/lib/hypo-ignore.mjs

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'fs';
-import { join, relative, basename } from 'path';
+import { join, relative, basename, resolve } from 'path';
 
 export function loadHypoIgnore(hypoDir) {
   const ignorePath = join(hypoDir, '.hypoignore');
@@ -10,6 +10,46 @@ export function loadHypoIgnore(hypoDir) {
     .filter((l) => l && !l.startsWith('#'));
 }
 
+// .hyposcanignore: scan-only exclusions (lint/graph/stats/query/verify/doctor
+// catalog scans). Deliberately NOT a privacy boundary: a match here is still
+// committed and still readable by hooks. Only isScanIgnored() below reads this
+// file. loadHypoIgnore()/isIgnored() must never see it, that is the whole
+// point of the split, so do not thread it into the pre-commit gate or
+// ingest --check.
+export function loadScanIgnore(hypoDir) {
+  const ignorePath = join(resolve(hypoDir), '.hyposcanignore');
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+}
+
+// Parsed .hyposcanignore patterns, cached per vault for the process lifetime.
+// The shared walker (wikilink.mjs) calls isScanIgnored() once per directory
+// entry, so re-reading this file on every call would turn a vault scan into
+// O(files) filesystem reads for one small file. Nothing writes
+// .hyposcanignore mid-process, so a stale cache is not a real scenario.
+//
+// Keyed on path.resolve(hypoDir), NOT the raw argument: a raw-string key lets
+// two different relative spellings of the SAME vault ('.', './') miss each
+// other (harmless, just a wasted read), but it also lets a relative key like
+// '.' collide ACROSS vaults when the caller cd's between them between calls —
+// vault B would silently reuse vault A's scan patterns. Resolving to an
+// absolute path first makes the key vault-identity-stable regardless of cwd
+// or spelling.
+const scanIgnoreCache = new Map();
+
+function cachedScanIgnore(hypoDir) {
+  const key = resolve(hypoDir);
+  let patterns = scanIgnoreCache.get(key);
+  if (patterns === undefined) {
+    patterns = loadScanIgnore(key);
+    scanIgnoreCache.set(key, patterns);
+  }
+  return patterns;
+}
+
 function globToRegex(glob) {
   return new RegExp(
     '^' +
@@ -39,12 +79,20 @@ export function isGeneratedArtifact(filePath, hypoDir) {
 }
 
 // Catalog/scan exclusion = privacy/.hypoignore patterns PLUS generated root
-// artifacts. Use this in tools that build the knowledge catalog (lint, graph,
-// stats, query, verify, crystallize, rename, doctor broken-links). Do NOT use it
-// in the pre-commit gate or ingest --check, which are privacy boundaries that
-// must stay on isIgnored()/.hypoignore alone.
+// artifacts PLUS scan-only/.hyposcanignore patterns (loaded and cached
+// internally, so callers keep passing only their privacy `patterns` array).
+// Use this in tools that build the knowledge catalog (lint, graph, stats,
+// query, verify, crystallize, rename, doctor broken-links). Do NOT use it in
+// the pre-commit gate or ingest --check, which are privacy boundaries that
+// must stay on isIgnored()/.hypoignore alone — OR-ing in .hyposcanignore here
+// only ever WIDENS what a scan skips, it can never make an .hypoignore match
+// committable, so that separation holds by construction.
 export function isScanIgnored(filePath, hypoDir, patterns) {
-  return isIgnored(filePath, hypoDir, patterns) || isGeneratedArtifact(filePath, hypoDir);
+  return (
+    isIgnored(filePath, hypoDir, patterns) ||
+    isGeneratedArtifact(filePath, hypoDir) ||
+    isIgnored(filePath, hypoDir, cachedScanIgnore(hypoDir))
+  );
 }
 
 export function isIgnored(filePath, hypoDir, patterns) {

package/scripts/lib/hypo-root.mjs

@@ -26,13 +26,20 @@ export function expandHome(p) {
 }
 
 /**
- * Resolve the Hypomnema root directory.
+ * Resolve the Hypomnema root directory, along with how it was resolved.
  * Checks HYPO_DIR env → hypo-config.md scan → ~/hypomnema default.
- * @returns {string} absolute path to Hypomnema root
+ *
+ * The `source` lets a caller tell "the user pointed us somewhere and it's
+ * empty" (an explicit misconfiguration worth failing loud on) apart from
+ * "nobody configured anything and none of the usual spots had a vault
+ * either" (a silent fallback, worth a quiet notice at most). resolveHypoRoot()
+ * itself collapses both into the same path, on purpose, for every caller that
+ * only ever wants a directory to hand to fs calls.
+ * @returns {{ root: string, source: 'env'|'marker'|'default' }}
  */
-export function resolveHypoRoot() {
+export function resolveHypoRootInfo() {
   if (process.env.HYPO_DIR) {
-    return expandHome(process.env.HYPO_DIR);
+    return { root: expandHome(process.env.HYPO_DIR), source: 'env' };
   }
 
   const candidates = [
@@ -46,8 +53,51 @@ export function resolveHypoRoot() {
   ];
 
   for (const c of candidates) {
-    if (existsSync(join(c, 'hypo-config.md'))) return c;
+    if (existsSync(join(c, 'hypo-config.md'))) return { root: c, source: 'marker' };
+  }
+
+  return { root: join(HOME, 'hypomnema'), source: 'default' };
+}
+
+/**
+ * Resolve the Hypomnema root directory.
+ * Checks HYPO_DIR env → hypo-config.md scan → ~/hypomnema default.
+ * @returns {string} absolute path to Hypomnema root
+ */
+export function resolveHypoRoot() {
+  return resolveHypoRootInfo().root;
+}
+
+/**
+ * Validate a resolved root against the hypo-config.md marker, for the
+ * read-only CLIs only (lint/stats/graph/query). Two failure classes need
+ * different loudness:
+ *   - `source === 'env'`: the caller pointed HYPO_DIR at a path with no
+ *     vault there — an explicit misconfiguration. Fail loud: stderr + exit 1.
+ *   - `source === 'default'` (or a stale `'marker'` hit): nobody configured
+ *     anything and none of the usual spots had a vault. CI (lint-runner,
+ *     release.yml) intentionally runs this way and must keep exiting 0 — but
+ *     the CLI must stop silently reporting "no issues found" / "no results"
+ *     as if it had actually scanned a wiki. Print a visible notice and tell
+ *     the caller, so it can adjust its own empty-result copy, then continue.
+ * A caller that received `hypoDir` from an explicit --hypo-dir=<path> flag
+ * (tests, other tooling) never calls this — that path is not auto-resolved
+ * and is trusted as-is, valid or not.
+ * @param {string} root
+ * @param {'env'|'marker'|'default'} source
+ * @returns {boolean} true when the vault is missing (caller should suppress
+ *   its own "nothing found" messaging in favor of this notice already
+ *   printed); false when a real vault was found and normal scanning should
+ *   proceed.
+ */
+export function checkVaultOrExit(root, source) {
+  if (existsSync(join(root, 'hypo-config.md'))) return false;
+
+  if (source === 'env') {
+    console.error(`Hypomnema vault not found at HYPO_DIR=${root} (no hypo-config.md).`);
+    process.exit(1);
   }
 
-  return join(HOME, 'hypomnema');
+  console.error('No Hypomnema vault found. Set HYPO_DIR or run inside a vault; nothing to scan.');
+  return true;
 }

package/scripts/lib/page-usage.mjs

@@ -11,6 +11,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
+import { currentDevice, scopeVisible, readVisibilityScope } from '../../hooks/hypo-shared.mjs';
 
 const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
 const DAY_MS = 86400000;
@@ -69,7 +70,13 @@ export function readPageUsage(hypoDir) {
 // within the last thresholdDays.
 export function aggregateColdCandidates(
   hypoDir,
-  { thresholdDays = 90, minLogSpanDays = 14, now = Date.now(), ignorePatterns = [] } = {},
+  {
+    thresholdDays = 90,
+    minLogSpanDays = 14,
+    now = Date.now(),
+    ignorePatterns = [],
+    device = currentDevice(),
+  } = {},
 ) {
   const records = readPageUsage(hypoDir);
   if (records.length === 0) return { status: 'insufficient-data', reason: 'no-records' };
@@ -110,6 +117,7 @@ export function aggregateColdCandidates(
       title: fm.title || slug,
       forms: formSet(slug),
       links: extractWikilinks(body),
+      scope: readVisibilityScope(content),
     });
   }
 
@@ -134,7 +142,12 @@ export function aggregateColdCandidates(
   }
 
   const candidates = pageList
-    .filter((p) => hasInbound.has(p.slug) && !intersects(p.forms, recentForms))
+    .filter(
+      (p) =>
+        hasInbound.has(p.slug) &&
+        !intersects(p.forms, recentForms) &&
+        scopeVisible(p.scope, device),
+    )
     .map((p) => ({ slug: p.slug, title: p.title }));
 
   return { status: 'ok', candidates };

package/scripts/lib/pkg-json.mjs

@@ -75,3 +75,43 @@ export function writePkgJsonAtomic(pkgJsonPath, data) {
     throw err;
   }
 }
+
+// Non-mutating read of the version a candidate install root's own package.json
+// carries, or null. Shared by writeDualSkipProvenance (what to stamp) and
+// upgrade.mjs's read-only report (what to preview/display) so both agree.
+export function readVersionAtRoot(root) {
+  try {
+    const v = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// Dual-install self-heal: writes a NARROW provenance correction to
+// pkgJsonPath, pointing pkgRoot/pkgVersion at the plugin registry's own
+// resolved root/version, while preserving every other existing field
+// (including a prior `commands` map — that map reflects the PLUGIN's own
+// install, not the caller's own run, so unlike a full plugin-mode metadata
+// write it must NOT be dropped or touched here).
+//
+// TOCTOU guard: the caller (upgrade.mjs) resolves `registryRoot` as usable via
+// a SEPARATE earlier read (resolveEnabledPluginRoot / usablePkgRoot) — that
+// root's own package.json can vanish or corrupt between that resolution and
+// this write. Re-reads the version HERE and refuses the correction outright if
+// it cannot, rather than stamp a NEW pkgRoot with a STALE version (the old
+// recorded one, or none): a wrong root+version pairing is worse than no
+// correction. Returns false without writing anything when refused — the
+// existing metadata is left exactly as it was, and the caller must not report
+// this as "corrected".
+export function writeDualSkipProvenance(pkgJsonPath, registryRoot) {
+  const registryVersion = readVersionAtRoot(registryRoot);
+  if (!registryVersion) return false;
+  const existing = readPkgJson(pkgJsonPath);
+  writePkgJsonAtomic(pkgJsonPath, {
+    ...existing,
+    pkgRoot: registryRoot,
+    pkgVersion: registryVersion,
+  });
+  return true;
+}

package/scripts/lib/plugin-detect.mjs

@@ -15,7 +15,8 @@
 // legacy `hypomnema@<marketplace>` key in `enabledPlugins` until they reinstall
 // as `hypo@<marketplace>`, and the guard must hold across that gap.
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 
 /**
  * @param {string} settingsPath  path to a Claude Code settings.json (e.g. ~/.claude/settings.json)
@@ -38,11 +39,18 @@ export function isHypomnemaPluginEnabled(settingsPath) {
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
 
-  const enabled = parsed.enabledPlugins;
+  return enabledKeyFrom(parsed.enabledPlugins) !== null;
+}
+
+// The exact enabledPlugins KEY (`hypo@<marketplace>` / legacy
+// `hypomnema@<marketplace>`) whose value is strictly true, or null. Same matching
+// rules as isHypomnemaPluginEnabled, but returns the identifier so a caller can
+// look that exact plugin up in the install registry rather than guessing among all
+// hypo-named entries.
+function enabledKeyFrom(enabled) {
   // enabledPlugins is an object map `{ "<name>@<marketplace>": true|false }`.
   // Anything else (absent, array, scalar) → not enabled.
-  if (!enabled || typeof enabled !== 'object' || Array.isArray(enabled)) return false;
-
+  if (!enabled || typeof enabled !== 'object' || Array.isArray(enabled)) return null;
   for (const [key, value] of Object.entries(enabled)) {
     if (value !== true) continue; // strictly true only — no truthy coercion
     // Require a real `name@marketplace` shape: an `@` that is neither the first
@@ -54,7 +62,89 @@ export function isHypomnemaPluginEnabled(settingsPath) {
     const name = key.slice(0, at);
     // Match the current plugin name and the legacy one (pre-rename) so the
     // guard holds across the migration window. Exact, case-sensitive.
-    if (name === 'hypo' || name === 'hypomnema') return true;
+    if (name === 'hypo' || name === 'hypomnema') return key;
+  }
+  return null;
+}
+
+/**
+ * @param {string} settingsPath  path to a Claude Code settings.json
+ * @returns {string|null} the exact `enabledPlugins` key of the enabled Hypomnema
+ *   plugin (`hypo@<marketplace>` or legacy `hypomnema@<marketplace>`), or null.
+ */
+export function enabledHypomnemaPluginKey(settingsPath) {
+  let raw;
+  try {
+    raw = readFileSync(settingsPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  return enabledKeyFrom(parsed.enabledPlugins);
+}
+
+function readPkgVersionAt(root) {
+  try {
+    const v = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// A pkgRoot is "usable" as a DURABLE install root only if it is an ABSOLUTE path to
+// a real package directory whose package.json carries a version. A relative path
+// (e.g. installPath ".") would be resolved against the caller's cwd and break the
+// vault git hook from any other directory; a version-less package.json cannot be
+// attributed a version without lying. A bare path that merely exists is a pointer
+// the runtime cannot resolve scripts through. Shared by init's registry resolution,
+// its durable-root fallback, and upgrade's dualSkip provenance correction so they
+// all agree on what is real.
+export function usablePkgRoot(pkgRoot) {
+  return (
+    typeof pkgRoot === 'string' &&
+    pkgRoot.length > 0 &&
+    isAbsolute(pkgRoot) &&
+    existsSync(join(pkgRoot, 'package.json')) &&
+    readPkgVersionAt(pkgRoot) !== null
+  );
+}
+
+// Resolve the enabled Hypomnema plugin's REAL install root from the plugin
+// registry (~/.claude/plugins/installed_plugins.json). POSITIVE attribution: it
+// looks up the EXACT key that settingsPath marks enabled (via
+// enabledHypomnemaPluginKey), not just any hypo-named entry — a disabled legacy or
+// other-marketplace entry must never be selected. Among that key's registry
+// entries it prefers the user-scope install (the one a plugin-enabled user runs),
+// falling back to any usable entry. Returns a usable absolute install root, or
+// null when the registry is absent/unreadable, names no entry for the enabled key,
+// or that entry is not a usable package dir. Fails open (null) on every
+// uncertainty — callers must treat null as "cannot positively resolve", never as
+// "resolved to nothing usable exists".
+export function resolveEnabledPluginRoot(settingsPath, registryPath) {
+  const key = enabledHypomnemaPluginKey(settingsPath);
+  if (!key) return null;
+  let reg;
+  try {
+    reg = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  } catch {
+    return null;
   }
-  return false;
+  const plugins =
+    reg && typeof reg.plugins === 'object' && !Array.isArray(reg.plugins) ? reg.plugins : null;
+  const entries = plugins && Array.isArray(plugins[key]) ? plugins[key] : null;
+  if (!entries) return null;
+  const paths = (scope) =>
+    entries
+      .filter((e) => e && (scope === undefined || e.scope === scope))
+      .map((e) => (typeof e.installPath === 'string' ? e.installPath : null))
+      .filter((p) => usablePkgRoot(p));
+  // Prefer the user-scope install, then any usable entry for this exact key.
+  return paths('user')[0] ?? paths(undefined)[0] ?? null;
 }

package/scripts/lib/project-create.mjs

@@ -28,7 +28,11 @@ import { resolveHypoRoot, expandHome } from './hypo-root.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..', '..');
-const TEMPLATE_DIR = join(PKG_ROOT, 'templates', 'projects', '_template');
+// Exported so other project-scaffolding call sites (crystallize.mjs's
+// session-close apply, which fills a MISSING index.md on a project that
+// bypassed createProject entirely) resolve the same template dir instead of
+// re-deriving the path.
+export const TEMPLATE_DIR = join(PKG_ROOT, 'templates', 'projects', '_template');
 
 const TEMPLATE_FILES = ['index.md', 'prd.md', 'hot.md', 'session-state.md'];
 

package/scripts/lib/rename-marker.mjs

@@ -0,0 +1,39 @@
+// scripts/lib/rename-marker.mjs
+//
+// The crash-recovery marker for rename.mjs --apply. Shared read-only path/parse
+// logic between the writer (rename.mjs) and the reader (doctor.mjs) so the two
+// never drift on where the marker lives or what shape it is in.
+//
+// Kept under .cache/ deliberately, matching every other runtime marker this repo
+// already writes there (sync-state.json, session-closed-*.marker, proposals/,
+// project-suggestions.json). Two things fall out of that placement for free:
+//   - it is JSON, not .md, so every vault walker (scripts/lib/wikilink.mjs) that
+//     only ever collects .md files simply never sees it — no lint/rename/graph
+//     scan needs to know this file exists.
+//   - .cache/ ships in templates/.hypoignore's default pattern list, so a scan
+//     that DOES walk directories rather than just filtering by extension
+//     (doctor's own checkBrokenLinks walker) is also covered on any vault that
+//     carries that baseline — which every vault already needs, since .cache/
+//     holds the pre-commit secret-gate's own state.
+// No .hyposcanignore entry or scan-logic change was needed to get this property;
+// it comes from where the file lives, not from a new exclusion rule.
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export const RENAME_MARKER_REL = '.cache/rename-in-progress.json';
+
+export function renameMarkerPath(hypoDir) {
+  return join(hypoDir, RENAME_MARKER_REL);
+}
+
+// Best-effort read: a missing or corrupt marker both mean "nothing to report" —
+// this runs inside doctor's health scan and must never throw.
+export function readRenameMarker(hypoDir) {
+  const path = renameMarkerPath(hypoDir);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}