hypomnema 1.5.0 → 1.6.0

package/scripts/lib/core-hooks.mjs

@@ -0,0 +1,156 @@
+// core-hooks.mjs - read the packaged hooks/hooks.json without side effects.
+//
+// The init installer (init.mjs loadHookMap) reads hooks.json, validates it, and
+// calls process.exit(1) on any malformation. That exit-on-error behavior is
+// correct for init but fatal for other consumers: reverse-capture wants to
+// reserve the core hook basenames so it never captures a core hook by mistake,
+// and it must not die because someone else's hooks.json is malformed.
+//
+// So this module owns only the read+parse step, exit-free. It returns a result
+// object; the caller decides what to do with a failure. init.mjs keeps its own
+// detailed validation + exit wrapper on top; reverse-capture skips the whole
+// hooks type when the result is not ok (better to capture nothing than to
+// capture a core hook).
+//
+// fail-closed: a result is ok only when the file reads, parses, AND has the
+// expected shape (a hooks registration map plus a shared array). A parsed but
+// oddly shaped hooks.json would yield a thin basename set, which is exactly the
+// gap through which a core hook could leak into capture. When the shape is off
+// we still attach the parsed cfg so init can run its own validation and emit its
+// own specific error, but ok is false so capture stays conservative.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Read and JSON-parse hooks/hooks.json from a package root. No process.exit, no
+ * top-level side effects.
+ *
+ * @param {string} pkgRoot  absolute path to the package root (contains hooks/)
+ * @returns {{ ok: true, cfg: object }
+ *   | { ok: false, error: string }
+ *   | { ok: false, error: string, cfg: * }}
+ *   On read or parse failure the `cfg` key is absent. On a successful parse the
+ *   `cfg` key is always present (even for null/array/scalar/shape-off inputs),
+ *   so a caller can discriminate read/parse failure from shape failure by the
+ *   presence of the `cfg` key. `ok` is true only when the shape is as expected.
+ */
+export function readCoreHooksConfig(pkgRoot) {
+  let raw;
+  try {
+    raw = readFileSync(join(pkgRoot, 'hooks', 'hooks.json'), 'utf-8');
+  } catch (err) {
+    return { ok: false, error: `cannot read hooks/hooks.json: ${err.message}` };
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, error: `hooks/hooks.json is not valid JSON: ${err.message}` };
+  }
+  // Parse succeeded: attach cfg unconditionally so init can run its own checks.
+  if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) {
+    return { ok: false, error: 'hooks/hooks.json must be a JSON object', cfg };
+  }
+  if (!cfg.hooks || typeof cfg.hooks !== 'object' || Array.isArray(cfg.hooks)) {
+    return { ok: false, error: 'hooks/hooks.json must contain a "hooks" object', cfg };
+  }
+  if (!Array.isArray(cfg.shared)) {
+    return { ok: false, error: 'hooks/hooks.json must contain a "shared" array', cfg };
+  }
+  // Nested shape: a structurally odd rung (event not an array, a group without a
+  // hooks array, a hook entry with no string command, a non-string shared element)
+  // is silently skipped by deriveCoreHookBasenames, yielding a THIN reserved set.
+  // That is the gap through which a core hook could leak into reverse-capture, so
+  // validate every rung and fail closed. cfg is still attached so init can run its
+  // own detailed validation and emit its own specific error.
+  for (const groups of Object.values(cfg.hooks)) {
+    if (!Array.isArray(groups)) {
+      return { ok: false, error: 'each hooks event must map to an array of groups', cfg };
+    }
+    for (const group of groups) {
+      if (typeof group === 'string') continue; // legacy bare-filename group
+      if (!group || typeof group !== 'object' || Array.isArray(group)) {
+        return { ok: false, error: 'each hook group must be an object or a filename string', cfg };
+      }
+      if (!Array.isArray(group.hooks)) {
+        return { ok: false, error: 'each hook group must contain a "hooks" array', cfg };
+      }
+      for (const hook of group.hooks) {
+        if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
+          return { ok: false, error: 'each hook entry must be an object', cfg };
+        }
+        if (typeof hook.command !== 'string') {
+          return { ok: false, error: 'each hook entry must have a string command', cfg };
+        }
+      }
+    }
+  }
+  for (const file of cfg.shared) {
+    if (typeof file !== 'string') {
+      return { ok: false, error: 'each "shared" entry must be a string', cfg };
+    }
+  }
+  return { ok: true, cfg };
+}
+
+// Match a bare .mjs basename with no path separators, whitespace, or quoting.
+// Applied to the LAST path segment only, so a command like
+// `node ${CLAUDE_PLUGIN_ROOT}/hooks/hypo-lookup.mjs` yields `hypo-lookup.mjs`.
+const MJS_BASENAME = /^[^\s/\\'"`]+\.mjs$/i;
+
+/**
+ * Extract the strict .mjs basename from a value that is either a bare filename
+ * or a full command string. Takes the last path segment (split on / and \) and
+ * accepts it only when it is a clean .mjs name. Returns null otherwise.
+ * @param {*} value
+ * @returns {string | null}
+ */
+function strictMjsBasename(value) {
+  if (typeof value !== 'string') return null;
+  const segments = value.trim().split(/[/\\]/);
+  const last = segments[segments.length - 1];
+  return MJS_BASENAME.test(last) ? last : null;
+}
+
+/**
+ * Derive the set of core hook .mjs basenames reserved by hooks.json: the union
+ * of every registered event command's basename and every `shared` array
+ * basename, lowercased. Walks defensively so a partially odd cfg yields a
+ * partial (never throwing) set; the fatal shape gate lives in
+ * readCoreHooksConfig.
+ *
+ * @param {object} cfg  parsed hooks.json (as returned in readCoreHooksConfig().cfg)
+ * @returns {Set<string>} lowercase .mjs basenames
+ */
+export function deriveCoreHookBasenames(cfg) {
+  const names = new Set();
+  const add = (value) => {
+    const base = strictMjsBasename(value);
+    if (base) names.add(base.toLowerCase());
+  };
+
+  if (cfg && typeof cfg === 'object' && cfg.hooks && typeof cfg.hooks === 'object') {
+    for (const groups of Object.values(cfg.hooks)) {
+      if (!Array.isArray(groups)) continue;
+      for (const group of groups) {
+        if (typeof group === 'string') {
+          // Legacy format: the group is a bare .mjs filename.
+          add(group);
+          continue;
+        }
+        if (group && typeof group === 'object' && Array.isArray(group.hooks)) {
+          for (const hook of group.hooks) {
+            if (hook && typeof hook === 'object') add(hook.command);
+          }
+        }
+      }
+    }
+  }
+
+  if (cfg && Array.isArray(cfg.shared)) {
+    for (const file of cfg.shared) add(file);
+  }
+
+  return names;
+}

package/scripts/lib/extensions.mjs

@@ -49,6 +49,140 @@ export const CODEX_TYPES = ['hooks', 'commands'];
 // Per-type expected file extension. Hooks are executable .mjs; the rest are .md.
 const TYPE_FILE_EXT = { hooks: '.mjs', commands: '.md', skills: '.md', agents: '.md' };
 
+// Singular manifest `type` value per directory (capture design §3). A captured
+// extension's sidecar manifest must declare a `type` matching its parent dir
+// before its `installName` is honored (guards against a mislabelled manifest
+// retargeting an install path).
+const TYPE_SINGULAR = { hooks: 'hook', commands: 'command', skills: 'skill', agents: 'agent' };
+
+// installName carrier (capture design §3): reverse-captured commands/agents/hooks
+// install under the user's ORIGINAL name, not the wiki `hypo-ext-*` storage name.
+// For hooks the installName also drives the reconstructed settings.json command
+// (buildHookCommand) and the sidecar manifest install name (P1), so all three
+// ownership paths stay aligned. Skills are not captured in the MVP.
+const INSTALLNAME_TYPES = new Set(['commands', 'agents', 'hooks']);
+
+// A valid installName stem: same conservative charset as SAFE_EXT_STEM but
+// WITHOUT the required hypo-ext- prefix (the whole point of C is to restore the
+// user's own name). Rejects path separators, traversal (leading dot blocks `..`
+// and `.`), and anything outside the charset.
+const SAFE_INSTALL_STEM = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+// Windows reserved device names (capture design §5 — the extensions-companion design chose hard-copy partly
+// for Windows compatibility, so an installName must never resolve to one).
+const WINDOWS_RESERVED = new Set([
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  'com1',
+  'com2',
+  'com3',
+  'com4',
+  'com5',
+  'com6',
+  'com7',
+  'com8',
+  'com9',
+  'lpt1',
+  'lpt2',
+  'lpt3',
+  'lpt4',
+  'lpt5',
+  'lpt6',
+  'lpt7',
+  'lpt8',
+  'lpt9',
+]);
+
+/**
+ * True iff `stem` is a syntactically valid, non-reserved installName (the reverse-capture design
+ * §5). Case-insensitive on the reservations so `Hypo-x` cannot slip past on a
+ * case-insensitive filesystem. Does NOT append an extension — callers add
+ * TYPE_FILE_EXT in code so a manifest can never inject the extension.
+ */
+export function isValidInstallStem(stem) {
+  if (typeof stem !== 'string' || !SAFE_INSTALL_STEM.test(stem)) return false;
+  // Reject `..` anywhere, not just a leading dot: an internal `a..b` passes the
+  // charset but parseExtKey (uninstall) rejects it, which would strand a captured
+  // file it can never remove. Keep the two validators in agreement.
+  if (stem.includes('..')) return false;
+  const lower = stem.toLowerCase();
+  if (lower === 'hypo' || lower.startsWith('hypo-')) return false; // reserved namespace
+  // Windows treats a device name reserved even WITH an extension (`con.v1`), so
+  // test the segment before the first dot, not just the whole stem.
+  const base = lower.split('.')[0];
+  if (WINDOWS_RESERVED.has(base)) return false;
+  return true;
+}
+
+/**
+ * Resolve the install filename for a discovered extension (capture design §3).
+ * Returns `{ installFile }` — the basename under `~/.claude/<type>/`. Defaults
+ * to `ext.file` (the wiki storage name) so existing hypo-ext-* extensions are
+ * untouched (backward compatible). Only commands/agents with a sidecar manifest
+ * whose `type` matches the directory AND whose `installName` is valid install
+ * under the user's original name. A present-but-invalid installName yields
+ * `{ skip, warn }` — the extension is dropped rather than silently installed
+ * under a surprising name.
+ */
+export function resolveInstallFile(ext) {
+  if (!INSTALLNAME_TYPES.has(ext.type) || !ext.manifestPath) {
+    return { installFile: ext.file };
+  }
+  const parsed = parseManifest(ext.manifestPath);
+  // A malformed hook manifest is reachable here (parseManifest validates hooks);
+  // fall back to the wiki storage name so the later sync loop, which re-parses and
+  // skips the malformed hook, still finds a consistent install path.
+  if (!parsed.ok) return { installFile: ext.file };
+  const m = parsed.manifest;
+  if (!m || m.type !== TYPE_SINGULAR[ext.type] || m.installName === undefined) {
+    return { installFile: ext.file };
+  }
+  if (!isValidInstallStem(m.installName)) {
+    return {
+      skip: true,
+      warn: `${ext.type}/${ext.file}: invalid installName "${m.installName}" — extension skipped`,
+    };
+  }
+  return { installFile: m.installName + TYPE_FILE_EXT[ext.type] };
+}
+
+/**
+ * Parse + validate a recorded pkg-json extension key `${type}/${installFile}`
+ * for destructive use (capture design §8 — uninstall traverses recorded keys, which
+ * come from an on-disk JSON we do not fully control). Returns
+ * `{ type, installFile }` only when the key is exactly one covered type, a
+ * single path segment for the filename (no separators / traversal), and the
+ * expected extension. Returns null otherwise so the caller skips it — never
+ * `join`s an untrusted key that could escape the extension directory.
+ */
+export function parseExtKey(key, coveredTypes) {
+  if (typeof key !== 'string') return null;
+  const slash = key.indexOf('/');
+  if (slash === -1) return null;
+  const type = key.slice(0, slash);
+  const installFile = key.slice(slash + 1);
+  if (!coveredTypes.includes(type)) return null;
+  // The filename portion must be a single safe segment: no further separators,
+  // no traversal, and it must end in the type's expected extension. Only HOOKS
+  // additionally track a `.manifest.json` sidecar copy in the SHA map, so the
+  // manifest suffix is accepted for hooks alone — accepting it for every type
+  // would let a forged `commands/x.manifest.json` key name a removable file that
+  // sync never owns (codex pre-commit CONCERN).
+  if (installFile.includes('/') || installFile.includes('\\')) return null;
+  if (installFile.includes('..') || installFile.startsWith('.')) return null;
+  const MANIFEST_SUFFIX = '.manifest.json';
+  const suffix =
+    type === 'hooks' && installFile.endsWith(MANIFEST_SUFFIX)
+      ? MANIFEST_SUFFIX
+      : TYPE_FILE_EXT[type];
+  if (!installFile.endsWith(suffix)) return null;
+  const stem = installFile.slice(0, -suffix.length);
+  if (stem.length === 0) return null;
+  return { type, installFile };
+}
+
 // Claude Code hook events (D3 allowlist). A manifest with an event outside this
 // set is malformed → the whole extension is skipped (no copy, no registration).
 export const HOOK_EVENT_ALLOWLIST = new Set([
@@ -184,9 +318,11 @@ export function parseManifest(path) {
 
 /**
  * Build the settings.json entries expected for the discovered hook extensions.
- * The command string is constructed here (never from the manifest) as
- * `node $HOME/.claude/hooks/<basename>`. Extensions whose manifest is missing or
- * not registrable yield no entry.
+ * The command string is constructed here (never from the manifest) via the shared
+ * `buildHookCommand`, using the installName-resolved install filename so a captured
+ * hook registers under its original name and its command matches the installed
+ * `.mjs`. Extensions whose manifest is missing, not registrable, or whose
+ * installName is invalid (resolveInstallFile skip) yield no entry.
  */
 export function buildExpectedSettingsEntries(discoveredHooks, targetHooksDir) {
   const entries = [];
@@ -194,7 +330,9 @@ export function buildExpectedSettingsEntries(discoveredHooks, targetHooksDir) {
     if (!ext.manifestPath) continue;
     const parsed = parseManifest(ext.manifestPath);
     if (!parsed.ok || !parsed.registrable) continue;
-    const command = `node ${targetHooksDir.replace(HOME, '$HOME')}/${ext.file}`;
+    const resolved = resolveInstallFile(ext);
+    if (resolved.skip) continue;
+    const command = buildHookCommand(targetHooksDir, resolved.installFile);
     entries.push({
       name: ext.name,
       file: ext.file,
@@ -207,6 +345,112 @@ export function buildExpectedSettingsEntries(discoveredHooks, targetHooksDir) {
   return entries;
 }
 
+/**
+ * The single source of the settings.json hook command string (capture design
+ * F4). Both the forward path (`buildExpectedSettingsEntries`) and the reverse
+ * strict parser (`parseCapturableHookCommand`) mirror this one shape so the two
+ * directions can never drift. `hooksDir` is `<HOME>/.claude/hooks`, rewritten to
+ * a `$HOME` literal so a captured registration stays portable across machines.
+ */
+export function buildHookCommand(hooksDir, installFile) {
+  return `node ${hooksDir.replace(HOME, '$HOME')}/${installFile}`;
+}
+
+// The exact canonical hook path prefix that `buildHookCommand` emits for a dir
+// under HOME. The strict parser accepts only this literal — an absolute path, a
+// `~`, or an env prefix all diverge and are rejected with a visible reason.
+const CAPTURABLE_HOOK_PATH_PREFIX = '$HOME/.claude/hooks/';
+const CAPTURABLE_NODE_PREFIX = 'node ';
+const MJS_EXT = '.mjs';
+
+/**
+ * Strict, fs-free parser for a capturable hook command (capture design F4). It
+ * accepts ONLY the byte-for-byte shape `buildHookCommand` produces for a dir
+ * under HOME: `node $HOME/.claude/hooks/<stem>.mjs`. Returns
+ * `{ ok:true, stem, basename }` on a match, else `{ ok:false, reason }` with a
+ * distinct reason per rejection axis so a caller can surface why a hook was not
+ * captured (never a silent drop). This is deliberately NOT the lenient
+ * `_extractCommandFileName` used by init: capture eligibility must be exact.
+ */
+export function parseCapturableHookCommand(command) {
+  if (typeof command !== 'string') return { ok: false, reason: 'not-a-string' };
+  // A newline in a command would break the one-line canonical shape and could
+  // smuggle a second statement past a prefix check.
+  if (/[\r\n]/.test(command)) return { ok: false, reason: 'contains-newline' };
+  if (!command.startsWith(CAPTURABLE_NODE_PREFIX)) {
+    return { ok: false, reason: 'bad-node-prefix' };
+  }
+  const rest = command.slice(CAPTURABLE_NODE_PREFIX.length);
+  // Reject extra leading whitespace (a double space or a tab after `node`): the
+  // builder emits exactly one space, so anything more is a lossy divergence.
+  if (rest.length === 0 || rest[0] === ' ' || rest[0] === '\t') {
+    return { ok: false, reason: 'bad-node-prefix' };
+  }
+  if (!rest.startsWith(CAPTURABLE_HOOK_PATH_PREFIX)) {
+    // Covers `~`, a relative path, an env prefix, and an absolute path — none
+    // start with the `$HOME/.claude/hooks/` literal.
+    return { ok: false, reason: 'path-not-under-home-hooks' };
+  }
+  const tail = rest.slice(CAPTURABLE_HOOK_PATH_PREFIX.length);
+  // The tail must be a single filename segment: no further separators (no
+  // subdirectory) and no traversal.
+  if (tail.includes('/') || tail.includes('\\') || tail.includes('..')) {
+    return { ok: false, reason: 'nested-segment' };
+  }
+  if (!tail.endsWith(MJS_EXT)) {
+    return { ok: false, reason: 'not-mjs' };
+  }
+  const stem = tail.slice(0, -MJS_EXT.length);
+  // Same stem gate as install (rejects the reserved hypo-* namespace, Windows
+  // device names, and out-of-charset names) so parse and install agree.
+  if (!isValidInstallStem(stem)) {
+    return { ok: false, reason: 'invalid-stem' };
+  }
+  return { ok: true, stem, basename: tail };
+}
+
+/**
+ * Pure, defensive walk of `settings.hooks[event][group].hooks[]` (capture design
+ * F4). Yields one record per hook entry:
+ * `{ event, matcher, type, timeout, command, hookKeys, groupKeys }`. `type` is the
+ * raw `entry.type` value (reverse-capture requires `'command'`, distinct from the
+ * `type` KEY that hookKeys reports). `matcher` is taken
+ * verbatim from the parent group with `''` normalized to absent (undefined),
+ * matching `parseManifest`/`registerSettings`. Any malformed rung (non-array
+ * event list, non-object group, non-array hook list, non-object hook) is skipped
+ * rather than throwing, so a hand-edited settings.json cannot crash the caller.
+ */
+export function scanSettingsHooks(settings) {
+  const records = [];
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) return records;
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return records;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || typeof group !== 'object' || Array.isArray(group)) continue;
+      const groupKeys = Object.keys(group);
+      let matcher = group.matcher;
+      if (matcher === '') matcher = undefined; // empty matcher === absent matcher
+      const hookList = group.hooks;
+      if (!Array.isArray(hookList)) continue;
+      for (const entry of hookList) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        records.push({
+          event,
+          matcher,
+          type: entry.type,
+          timeout: entry.timeout,
+          command: entry.command,
+          hookKeys: Object.keys(entry),
+          groupKeys,
+        });
+      }
+    }
+  }
+  return records;
+}
+
 /** Read the full hypo-pkg.json without any side effect (cf. pkg-json.readPkgJson,
  * which renames a corrupt file — unsafe for read-only callers, plan §5 #3). */
 function readFullPkgNoMutate(pkgPath) {
@@ -387,9 +631,67 @@ export function syncExtensions({
 
   const expectedHookExts = [];
 
+  // capture design §3/§3a: resolve each extension's install filename (installName
+  // decoupling) and detect duplicate install targets BEFORE any hard-copy. A
+  // case-folded collision on `${type}/${installFile}` (two wiki files mapping to
+  // the same install path, or a case-only clash on macOS/Windows) skips the
+  // WHOLE group — otherwise file traversal order would decide ownership and
+  // overwrite/skip unpredictably. Keyed by ext object identity.
+  const installFileByExt = new Map();
+  const dupSkip = new Set();
+  for (const type of types) {
+    const seen = new Map(); // case-folded `${type}/${installFile}` → first ext
+    for (const ext of discovered[type]) {
+      const res = resolveInstallFile(ext);
+      if (res.skip) {
+        dupSkip.add(ext);
+        result.warnings.push(res.warn);
+        continue;
+      }
+      installFileByExt.set(ext, res.installFile);
+      const norm = `${type}/${res.installFile.toLowerCase()}`;
+      const first = seen.get(norm);
+      if (first !== undefined) {
+        dupSkip.add(ext);
+        dupSkip.add(first);
+        result.warnings.push(
+          `${type}/${res.installFile} install target claimed by multiple extensions — all skipped (rename installName)`,
+        );
+      } else {
+        seen.set(norm, ext);
+      }
+    }
+  }
+
+  // Preserve the ownership record of an already-installed file whose extension we
+  // now skip on a duplicate-target collision. Without this, the newSHAs map (which
+  // replaces the target map wholesale) would drop the recorded SHA and orphan the
+  // previously-owned installed copy — it would linger on disk, untracked by doctor
+  // and unreachable by uninstall (codex pre-commit BLOCKER).
+  for (const ext of dupSkip) {
+    const inst = installFileByExt.get(ext);
+    if (!inst) continue; // invalid-installName skip: never owned
+    // Preserve BOTH ownership keys a hook records: the main `.mjs` AND its paired
+    // `.manifest.json` sidecar. Preserving only the main key (codex pre-commit
+    // CONCERN) would drop the sidecar SHA on a duplicate-target collision, leaving
+    // the installed manifest copy on disk untracked by doctor and unreachable by
+    // uninstall. commands/agents have no sidecar, so their single key is preserved.
+    const keys = [`${ext.type}/${inst}`];
+    if (ext.type === 'hooks') {
+      keys.push(`${ext.type}/${inst.replace(/\.mjs$/, '.manifest.json')}`);
+    }
+    for (const key of keys) {
+      if (recorded[key] !== undefined && newSHAs[key] === undefined) newSHAs[key] = recorded[key];
+    }
+  }
+
   for (const type of types) {
     const typeDir = join(targetRoot, type);
     for (const ext of discovered[type]) {
+      if (dupSkip.has(ext)) continue;
+      // Install under the manifest-declared installName (capture design §3) or, by
+      // default, the wiki storage name (backward compatible).
+      const installFile = installFileByExt.get(ext) ?? ext.file;
       // D3: validate the manifest before touching the filesystem.
       let manifestParsed = null;
       if (type === 'hooks') {
@@ -408,11 +710,12 @@ export function syncExtensions({
 
       if (apply) mkdirSync(typeDir, { recursive: true });
 
-      // (2) hard-copy the main file.
-      const fileKey = `${type}/${ext.file}`;
+      // (2) hard-copy the main file. Key + destPath use installFile so the
+      // recorded SHA map, doctor, and uninstall all agree on the install path.
+      const fileKey = `${type}/${installFile}`;
       const fileRes = copyOne({
         srcPath: ext.srcPath,
-        destPath: join(typeDir, ext.file),
+        destPath: join(typeDir, installFile),
         key: fileKey,
         recordedSHA: recorded[fileKey],
         apply,
@@ -438,10 +741,15 @@ export function syncExtensions({
         manifestParsed &&
         manifestParsed.ok
       ) {
-        const mKey = `${type}/${ext.manifestName}`;
+        // P1: derive the sidecar install name from the sibling `.mjs` installFile
+        // so the manifest copy + SHA key follow installName exactly as the hook
+        // file does. For a wiki-authored hook (no installName) installFile is
+        // `ext.file`, so this equals the old `ext.manifestName` (no regression).
+        const installManifestName = installFile.replace(/\.mjs$/, '.manifest.json');
+        const mKey = `${type}/${installManifestName}`;
         const mRes = copyOne({
           srcPath: ext.manifestPath,
-          destPath: join(typeDir, ext.manifestName),
+          destPath: join(typeDir, installManifestName),
           key: mKey,
           recordedSHA: recorded[mKey],
           apply,

package/scripts/lib/page-usage.mjs

@@ -0,0 +1,141 @@
+// page-usage.mjs: read-only aggregation over .cache/page-usage.jsonl (B3)
+//
+// The lookup hook appends one JSONL record per injected page slug (see
+// hooks/hypo-shared.mjs recordLookupUsage). This lib reads that log and derives
+// "lookup-cold candidates": pages that have inbound wikilinks (so the graph
+// treats them as live) but have not been injected by lookup within a recency
+// window. It writes nothing and is only invoked from scripts (crystallize), so
+// it never touches the per-prompt hook hot path.
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
+const DAY_MS = 86400000;
+
+// The distinct link forms a slug may appear as in a [[wikilink]] or in the log:
+// its full path, its basename, and (when nested) the path minus its first
+// segment. Matching by form-set intersection bridges the gap between the log's
+// index-matched slug form and the reverse index's [[wikilink]] form.
+function formSet(slug) {
+  const f = slugForms(slug);
+  const s = new Set([f.full, f.bare]);
+  if (f.dirRel) s.add(f.dirRel);
+  return s;
+}
+
+function intersects(a, b) {
+  for (const x of a) if (b.has(x)) return true;
+  return false;
+}
+
+// Read every record from the usage log, skipping malformed lines. Returns [] if
+// the log is absent or unreadable (fail-soft: aggregation is advisory).
+export function readPageUsage(hypoDir) {
+  const path = join(hypoDir, PAGE_USAGE_REL);
+  if (!existsSync(path)) return [];
+  let text;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      // Only keep plain objects. A bare `null`, number, string, or array is
+      // valid JSON but not a record; keeping it would crash the field access in
+      // aggregateColdCandidates (and crystallize calls that outside a try).
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+      // malformed line → skip (log is append-only and may be partially written)
+    }
+  }
+  return records;
+}
+
+// Derive lookup-cold candidates. Guards against cold-start: if there are no
+// records, or the observed log span is shorter than minLogSpanDays, returns
+// { status: 'insufficient-data' } so a fresh log doesn't flag the whole vault.
+// Otherwise returns { status: 'ok', candidates: [{ slug, title }] } for pages
+// that have >= 1 inbound wikilink from another page yet have not been logged
+// within the last thresholdDays.
+export function aggregateColdCandidates(
+  hypoDir,
+  { thresholdDays = 90, minLogSpanDays = 14, now = Date.now(), ignorePatterns = [] } = {},
+) {
+  const records = readPageUsage(hypoDir);
+  if (records.length === 0) return { status: 'insufficient-data', reason: 'no-records' };
+
+  const times = records.map((r) => Date.parse(r.ts)).filter((t) => Number.isFinite(t));
+  if (times.length === 0) return { status: 'insufficient-data', reason: 'no-timestamps' };
+  const span = Math.max(...times) - Math.min(...times);
+  if (span < minLogSpanDays * DAY_MS) {
+    return { status: 'insufficient-data', reason: 'span-too-short' };
+  }
+
+  // Forms of every slug logged within the recency window.
+  const recentCutoff = now - thresholdDays * DAY_MS;
+  const recentForms = new Set();
+  for (const r of records) {
+    const t = Date.parse(r.ts);
+    if (!Number.isFinite(t) || t < recentCutoff) continue;
+    if (typeof r.slug !== 'string' || !r.slug) continue;
+    for (const form of formSet(r.slug)) recentForms.add(form);
+  }
+
+  // Build the page list with slug, title, forms, and outbound links.
+  const pagesDir = join(hypoDir, 'pages');
+  const pageList = [];
+  for (const { path, rel } of collectPagesCrystallize(pagesDir, hypoDir, ignorePatterns)) {
+    let content;
+    try {
+      content = readFileSync(path, 'utf-8');
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(content);
+    if (!fm) continue;
+    const slug = rel.replace(/\.md$/, '');
+    const body = content.replace(/^---[\s\S]*?---/, '');
+    pageList.push({
+      slug,
+      title: fm.title || slug,
+      forms: formSet(slug),
+      links: extractWikilinks(body),
+    });
+  }
+
+  // Reverse index: which page slugs receive >= 1 inbound link from another page.
+  const formOwners = new Map(); // form → Set<page slug>
+  for (const p of pageList) {
+    for (const form of p.forms) {
+      if (!formOwners.has(form)) formOwners.set(form, new Set());
+      formOwners.get(form).add(p.slug);
+    }
+  }
+  const hasInbound = new Set();
+  for (const p of pageList) {
+    for (const link of p.links) {
+      const targets = new Set();
+      for (const form of formSet(link)) {
+        const owners = formOwners.get(form);
+        if (owners) for (const o of owners) targets.add(o);
+      }
+      for (const t of targets) if (t !== p.slug) hasInbound.add(t);
+    }
+  }
+
+  const candidates = pageList
+    .filter((p) => hasInbound.has(p.slug) && !intersects(p.forms, recentForms))
+    .map((p) => ({ slug: p.slug, title: p.title }));
+
+  return { status: 'ok', candidates };
+}