hypomnema 1.7.1 → 1.7.2

package/hooks/hypo-shared.mjs

@@ -24,7 +24,7 @@ import {
 import { join, relative, basename, dirname, isAbsolute } from 'path';
 import { homedir, hostname, tmpdir } from 'os';
 import { spawnSync } from 'child_process';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
 import { fileURLToPath } from 'url';
 
 const HOME = homedir();
@@ -149,7 +149,14 @@ function readCachedPkgRoot() {
 // Hypomnema — e.g. `$HOME/package.json` from an unrelated project. This
 // contract answers "is this a real, resolvable directory", not "is this OUR
 // package". Callers that need the latter also require self-containment.
-function isUsablePkgRootLocal(pkgRoot) {
+//
+// Exported so scripts/doctor.mjs can apply the SAME predicate to a sidecar's
+// recorded pkgRoot that readVerifiedProvenancePkgRoot() below applies at
+// runtime — doctor used to hand-roll a thinner name+hash check that a
+// version-less "name":"hypomnema" root would pass while the runtime resolver
+// rejects it, so doctor could PASS a sidecar the runtime treats as null. The
+// import direction stays scripts/ → hooks/, never the reverse.
+export function isUsablePkgRootLocal(pkgRoot) {
   if (typeof pkgRoot !== 'string' || !pkgRoot || !isAbsolute(pkgRoot)) return false;
   try {
     const v = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).version;
@@ -205,16 +212,25 @@ function candidateContainsRunningModule(candidateRoot, ownRealPath) {
 // candidateContainsRunningModule rejects it: that ancestor's own hooks/
 // subdirectory (if it even has one) is not this file.
 //
-// Bounded walk: up to 6 candidate ancestors above hooks/'s own parent (the
+// Bounded walk: up to 6 candidate ancestors above hooksDir's own parent (the
 // ordinary root sits at the very first one; a few extra levels tolerate an
 // unusual nesting depth). Never throws, fails open to null on any error.
-function selfLocationPkgRoot() {
-  let hooksDir, ownRealPath;
+//
+// Split out from selfLocationPkgRoot() (below) so scripts/doctor.mjs can ask
+// the same question about an ARBITRARY installed hooks directory
+// (~/.claude/hooks, ~/.codex/hooks) instead of only about wherever THIS
+// running module happens to live. doctor needs that to tell "self-location
+// genuinely can't resolve for this install" (the standalone-copy steady
+// state, silence is correct) apart from "self-location would resolve but the
+// provenance sidecar is missing/broken" (a real gap — see CONCERN 4's
+// PKG_ROOT-null-and-silent fix in checkProvenanceSidecar). Exported;
+// scripts/ → hooks/ stays the only allowed import direction.
+export function selfLocationPkgRootFrom(hooksDir) {
+  let ownRealPath;
   try {
-    hooksDir = dirname(fileURLToPath(import.meta.url));
     ownRealPath = realpathSync(join(hooksDir, 'hypo-shared.mjs'));
   } catch {
-    return null; // can't even resolve our own path — nothing to self-contain against
+    return null; // can't even resolve the module at hooksDir — nothing to self-contain against
   }
   try {
     let dir = dirname(hooksDir); // first candidate: the ordinary root, one level above hooks/
@@ -232,16 +248,93 @@ function selfLocationPkgRoot() {
   }
 }
 
+function selfLocationPkgRoot() {
+  let hooksDir;
+  try {
+    hooksDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return null; // can't even resolve our own path
+  }
+  return selfLocationPkgRootFrom(hooksDir);
+}
+
+// Copy-time provenance sidecar (`.hypo-provenance.json`, written next to a
+// standalone-copied hooks/ dir by installHooks/applyHookFiles — see
+// scripts/lib/pkg-provenance.mjs, the writer half of this contract) is the
+// ONLY fallback resolvePkgRoot() gets when self-location can't resolve. The
+// filename and the "hypomnema" name check below must stay byte-identical
+// with scripts/lib/pkg-provenance.mjs — hooks can't import scripts/ (no
+// reaching outside hooks/), so the contract is duplicated, not shared.
+//
+// This is accidental-staleness protection, not a security boundary: any
+// process running as this OS user can edit this JSON file (or hypo-shared.mjs
+// itself) freely. It only catches what installHooks/applyHookFiles left
+// unguarded before this fix — a manual-install hooks/ copy left pointing at
+// an old pkgVersion because a skip-then-refresh-the-cache-anyway sequence
+// (init re-run against an unchanged hooks/ dir) recorded a version the copy
+// on disk never actually became.
+//
+// Producer proof, BOTH required before this pkgRoot is trusted:
+//   - the recorded pkgRoot's package.json "name" must be "hypomnema" (not
+//     merely "some usable versioned package.json" — isUsablePkgRootLocal
+//     alone would accept $HOME/package.json from an unrelated project)
+//   - the recorded hypoSharedSha256 must match the SHA-256 of THIS running
+//     hypo-shared.mjs file — ties the sidecar to the exact copy it was
+//     written next to, so a sidecar surviving a partial re-install (new
+//     hooks/*.mjs dropped in, old sidecar left behind) is rejected rather
+//     than silently trusted.
+//
+// Scope, stated honestly: hypoSharedSha256 pins ONE file — this file. A
+// sidecar surviving a re-install that touched some OTHER hook (e.g.
+// hypo-personal-check.mjs got a new version, hypo-shared.mjs itself didn't
+// change a byte) still passes this check and PKG_ROOT still resolves,
+// because the running module — the one thing this function can verify
+// without cost — never changed. Catching that wider drift needs hashing
+// every file hooks.json wires up, which is too expensive to do on every
+// hook load (this function runs on every single hook invocation); that
+// broader, once-per-`doctor`-run check is `hooksDigest`
+// (scripts/lib/pkg-provenance.mjs's computeHooksDigest, verified by
+// scripts/doctor.mjs), deliberately NOT read here.
+const PROVENANCE_FILENAME = '.hypo-provenance.json';
+const EXPECTED_PKG_NAME = 'hypomnema';
+
+function readVerifiedProvenancePkgRoot(hooksDir) {
+  try {
+    const raw = JSON.parse(readFileSync(join(hooksDir, PROVENANCE_FILENAME), 'utf-8'));
+    const { pkgRoot, hypoSharedSha256 } = raw || {};
+    if (!isUsablePkgRootLocal(pkgRoot)) return null;
+    const producerPkgJson = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8'));
+    if (producerPkgJson.name !== EXPECTED_PKG_NAME) return null;
+    if (typeof hypoSharedSha256 !== 'string' || !hypoSharedSha256) return null;
+    const ownHash = createHash('sha256')
+      .update(readFileSync(join(hooksDir, 'hypo-shared.mjs')))
+      .digest('hex');
+    if (ownHash !== hypoSharedSha256) return null;
+    return pkgRoot;
+  } catch {
+    return null;
+  }
+}
+
 // Resolution order: self-location wins whenever it resolves — it is a direct,
 // self-containment-verified fact about the code currently running, not an
 // inference. Only when it cannot resolve (the standalone-copied hooks case
-// above, or a genuine read failure) does the cache get to answer, and only
-// after passing the same usable-root contract as everything else here.
+// above, or a genuine read failure) does the verified provenance sidecar get
+// to answer, checked against the same directory this module is actually
+// running from. The cache (readCachedPkgRoot/hypo-pkg.json) is deliberately
+// NOT a resolution fallback here — a disagreeing provenance sidecar means
+// "stop", not "ask the cache", because the cache is exactly what can be
+// stale (that staleness is this fix's whole premise). readCachedPkgRoot stays
+// in this file only for pkgRootDriftStatus()'s surfacing comparison below.
 function resolvePkgRoot() {
   const self = selfLocationPkgRoot();
   if (self) return self;
-  const cached = readCachedPkgRoot();
-  return isUsablePkgRootLocal(cached) ? cached : null;
+  try {
+    const hooksDir = dirname(fileURLToPath(import.meta.url));
+    return readVerifiedProvenancePkgRoot(hooksDir);
+  } catch {
+    return null;
+  }
 }
 export const PKG_ROOT = resolvePkgRoot();
 
@@ -709,7 +802,10 @@ function gitIgnoresPageUsageCached(hypoDir, sessionId, probeFn = runGitCheckIgno
   if (!probe || (probe.status !== 0 && probe.status !== 1)) {
     if (scoped) {
       try {
-        writeFileSync(cachePath, JSON.stringify({ unavailableUntil: Date.now() + PROBE_BACKOFF_MS }));
+        writeFileSync(
+          cachePath,
+          JSON.stringify({ unavailableUntil: Date.now() + PROBE_BACKOFF_MS }),
+        );
       } catch {
         // non-fatal; the probe just runs again next prompt
       }
@@ -1628,89 +1724,89 @@ export function withFileLock(targetPath, fn, opts = {}) {
   let loggedLiveHolder = false;
   let loggedSteal = false;
   try {
-  for (;;) {
-    try {
-      if (!staged) {
+    for (;;) {
+      try {
+        if (!staged) {
+          try {
+            writeFileSync(tmpPath, String(process.pid), { flag: 'wx' });
+            staged = true;
+          } catch (stageErr) {
+            // Staging fails for the same reason acquisition does — an unwritable
+            // directory — and `openSync(lock,'wx')` used to report exactly that as
+            // EEXIST whenever a lock was already sitting there, sending it down the
+            // contention path. Preserve that: contend if a lock exists, and surface
+            // a genuine write failure otherwise rather than masking it as a timeout.
+            if (!existsSync(lockPath)) throw stageErr;
+            throw Object.assign(new Error('lock-contended'), { code: 'EEXIST' });
+          }
+        }
+        // Kept separate from staging on purpose: EPERM/EMLINK from the link are
+        // real failures, not contention, and must not decay into ELOCKTIMEOUT.
+        linkSync(tmpPath, lockPath);
+        break;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        // Held by another writer. Steal ONLY a demonstrably stale lock; otherwise
+        // wait and eventually time out. The stat and the unlink are handled
+        // separately on purpose: an un-removable stale lock (EACCES/EPERM/EBUSY)
+        // and a fresh lock must both fall through to the timeout check — never
+        // `continue` past it, or an un-unlinkable lock spins forever and violates
+        // the timeoutMs → ELOCKTIMEOUT contract (caller falls to the proposal gate).
+        let stale = false;
         try {
-          writeFileSync(tmpPath, String(process.pid), { flag: 'wx' });
-          staged = true;
-        } catch (stageErr) {
-          // Staging fails for the same reason acquisition does — an unwritable
-          // directory — and `openSync(lock,'wx')` used to report exactly that as
-          // EEXIST whenever a lock was already sitting there, sending it down the
-          // contention path. Preserve that: contend if a lock exists, and surface
-          // a genuine write failure otherwise rather than masking it as a timeout.
-          if (!existsSync(lockPath)) throw stageErr;
-          throw Object.assign(new Error('lock-contended'), { code: 'EEXIST' });
+          // Steal-eligible by age alone; liveness is checked separately below
+          // before we actually act on it.
+          stale = Date.now() - statSync(lockPath).mtimeMs > staleMs;
+        } catch (statErr) {
+          if (statErr.code === 'ENOENT') continue; // lock vanished; retry create now
+          throw statErr; // unexpected stat failure — surface it, don't mask
         }
-      }
-      // Kept separate from staging on purpose: EPERM/EMLINK from the link are
-      // real failures, not contention, and must not decay into ELOCKTIMEOUT.
-      linkSync(tmpPath, lockPath);
-      break;
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      // Held by another writer. Steal ONLY a demonstrably stale lock; otherwise
-      // wait and eventually time out. The stat and the unlink are handled
-      // separately on purpose: an un-removable stale lock (EACCES/EPERM/EBUSY)
-      // and a fresh lock must both fall through to the timeout check — never
-      // `continue` past it, or an un-unlinkable lock spins forever and violates
-      // the timeoutMs → ELOCKTIMEOUT contract (caller falls to the proposal gate).
-      let stale = false;
-      try {
-        // Steal-eligible by age alone; liveness is checked separately below
-        // before we actually act on it.
-        stale = Date.now() - statSync(lockPath).mtimeMs > staleMs;
-      } catch (statErr) {
-        if (statErr.code === 'ENOENT') continue; // lock vanished; retry create now
-        throw statErr; // unexpected stat failure — surface it, don't mask
-      }
-      if (stale) {
-        const holderPid = readLockHolderPid(lockPath);
-        if (holderPid !== null && isPidAlive(holderPid)) {
-          // LIVE holder preempted past staleMs: do NOT steal. Surface it so the
-          // preemption is visible, then fall through to the poll/timeout path
-          // below instead of racing a second writer into the critical section.
-          if (!loggedLiveHolder) {
+        if (stale) {
+          const holderPid = readLockHolderPid(lockPath);
+          if (holderPid !== null && isPidAlive(holderPid)) {
+            // LIVE holder preempted past staleMs: do NOT steal. Surface it so the
+            // preemption is visible, then fall through to the poll/timeout path
+            // below instead of racing a second writer into the critical section.
+            if (!loggedLiveHolder) {
+              console.error(
+                `[hypomnema] withFileLock: NOT stealing ${lockPath} — holder pid ${holderPid} is still alive past staleMs=${staleMs}`,
+              );
+              loggedLiveHolder = true;
+            }
+            stale = false;
+          } else if (!loggedSteal) {
+            // Also once per acquire: an un-removable stale lock re-enters this
+            // branch on every poll, and the steal is one event either way.
             console.error(
-              `[hypomnema] withFileLock: NOT stealing ${lockPath} — holder pid ${holderPid} is still alive past staleMs=${staleMs}`,
+              `[hypomnema] withFileLock: stealing stale lock ${lockPath}` +
+                (holderPid !== null
+                  ? ` (holder pid ${holderPid} is no longer running)`
+                  : ' (no readable holder pid — pre-liveness lockfile)'),
             );
-            loggedLiveHolder = true;
+            loggedSteal = true;
           }
-          stale = false;
-        } else if (!loggedSteal) {
-          // Also once per acquire: an un-removable stale lock re-enters this
-          // branch on every poll, and the steal is one event either way.
-          console.error(
-            `[hypomnema] withFileLock: stealing stale lock ${lockPath}` +
-              (holderPid !== null
-                ? ` (holder pid ${holderPid} is no longer running)`
-                : ' (no readable holder pid — pre-liveness lockfile)'),
-          );
-          loggedSteal = true;
         }
-      }
-      if (stale) {
-        try {
-          unlinkSync(lockPath);
-          continue; // stole it; retry the create immediately
-        } catch (unlinkErr) {
-          if (unlinkErr.code === 'ENOENT') continue; // another stealer won; retry
-          // Cannot remove it: do NOT spin — fall through to timeout/sleep so
-          // acquisition eventually throws ELOCKTIMEOUT instead of hanging.
+        if (stale) {
+          try {
+            unlinkSync(lockPath);
+            continue; // stole it; retry the create immediately
+          } catch (unlinkErr) {
+            if (unlinkErr.code === 'ENOENT') continue; // another stealer won; retry
+            // Cannot remove it: do NOT spin — fall through to timeout/sleep so
+            // acquisition eventually throws ELOCKTIMEOUT instead of hanging.
+          }
         }
+        if (Date.now() - start > timeoutMs) {
+          // Tagged so callers can distinguish "could not get the lock" (fall to the
+          // proposal gate) from a real fn() write error (mkdir/openSync/disk-full),
+          // which must NOT be masked as a timeout.
+          const e = new Error(`lock-timeout: ${lockPath}`);
+          e.code = 'ELOCKTIMEOUT';
+          throw e;
+        }
+        sleepSync(pollMs);
       }
-      if (Date.now() - start > timeoutMs) {
-        // Tagged so callers can distinguish "could not get the lock" (fall to the
-        // proposal gate) from a real fn() write error (mkdir/openSync/disk-full),
-        // which must NOT be masked as a timeout.
-        const e = new Error(`lock-timeout: ${lockPath}`);
-        e.code = 'ELOCKTIMEOUT';
-        throw e;
-      }
-      sleepSync(pollMs);
     }
-  }
   } finally {
     // The sibling is only ever a staging file: once linked, the lock IS the
     // link, and on every failure path it must not survive as litter.
@@ -4154,7 +4250,11 @@ const CLOSE_COMMIT_MESSAGE = new RegExp(
  *   is the YYYY-MM-DD captured from the artifact's own heading, or null for a
  *   commit-message match (the caller already has the commit's date).
  */
-export function detectSessionCloseArtifact({ path = null, content = null, commitMessage = null } = {}) {
+export function detectSessionCloseArtifact({
+  path = null,
+  content = null,
+  commitMessage = null,
+} = {}) {
   if (typeof commitMessage === 'string' && CLOSE_COMMIT_MESSAGE.test(commitMessage)) {
     return { matched: true, kind: 'commit-message', date: null };
   }

package/hooks/version-check.mjs

@@ -430,6 +430,53 @@ export function clearPkgRootDriftNotified(path) {
   }
 }
 
+// ── pkgRoot-null notice ─────────────────────────────────────────────────────
+// A DIFFERENT failure than drift above: drift only ever fires when
+// self-location resolved (PKG_ROOT is non-null, just disagreeing with the
+// cache). This one fires when PKG_ROOT itself resolved to null — self-location
+// failed AND no verified provenance sidecar covered it — the case where
+// PreCompact's lint/feedback calls silently no-op because they have no root to
+// shell scripts through. The two conditions can never both hold in the same
+// session (drift requires a non-null self-location), so there is no "which
+// wins" question in practice, but the two use separate cache fields regardless
+// so neither implementation depends on that being true forever.
+// Boolean (not a pair-key like drift) — the notified state is just "already
+// told them this session's install has no resolvable pkgRoot".
+
+/** Has the PKG_ROOT-null state already been surfaced since it last cleared? */
+export function pkgRootNullAlreadyNotified(cache) {
+  return Boolean(cache && cache.pkgRootNullNotified === true);
+}
+
+/** Record that the PKG_ROOT-null banner was shown (read-merge-write). */
+export function markPkgRootNullNotified(path) {
+  try {
+    const cache = readCache(path) || {};
+    cache.pkgRootNullNotified = true;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Clear a previously-recorded PKG_ROOT-null mark once PKG_ROOT resolves again
+ * (self-location or a verified provenance sidecar). Without this, a null state
+ * that resolves and then recurs later (e.g. the provenance sidecar's hash
+ * binding breaks again after a partial re-install) would stay silently
+ * suppressed forever. Read-merge-write, best-effort.
+ */
+export function clearPkgRootNullNotified(path) {
+  try {
+    const cache = readCache(path);
+    if (!cache || !('pkgRootNullNotified' in cache)) return;
+    delete cache.pkgRootNullNotified;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * Shared one-line message for the init/upgrade downgrade guard (P). `op` is
  * 'init' or 'upgrade'. Kept here so guard text stays identical across both CLIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "scripts/lib/hypo-root.mjs",
     "scripts/lib/page-usage.mjs",
     "scripts/lib/pkg-json.mjs",
+    "scripts/lib/pkg-provenance.mjs",
     "scripts/lib/plugin-detect.mjs",
     "scripts/lib/project-create.mjs",
     "scripts/lib/rename-marker.mjs",

package/scripts/doctor.mjs

@@ -31,6 +31,8 @@ import {
   detectSessionCloseArtifact,
   localAndUtcDates,
   SESSION_CLOSED_MARKER_STALE_MS,
+  isUsablePkgRootLocal,
+  selfLocationPkgRootFrom,
 } from '../hooks/hypo-shared.mjs';
 import { listProposals } from '../hooks/proposal-store.mjs';
 import {
@@ -50,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 ───────────────────────────────────────────────────────────
 //
@@ -320,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) {
@@ -813,11 +824,9 @@ function deriveCommitProjects(hypoDir, hash) {
   // 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' },
-  );
+  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')) {
@@ -1230,6 +1239,8 @@ function checkCodexPaths() {
     );
   }
 
+  checkProvenanceSidecar(codexHooks, 'Codex hooks/.hypo-provenance.json');
+
   const settingsPath = join(HOME, '.codex', 'settings.json');
   if (!existsSync(settingsPath)) {
     warn(
@@ -1828,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

package/scripts/init.mjs

@@ -48,6 +48,7 @@ import {
   readFileIfRegular,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
+import { writeProvenanceSidecar } from './lib/pkg-provenance.mjs';
 import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 import {
@@ -458,6 +459,14 @@ function installHooks(targetDir, dryRun) {
     if (!dryRun) copyFileSync(join(HOOKS_SRC, file), dest);
     log('created', dest);
   }
+  // Refresh the provenance sidecar every run, even when every .mjs above was
+  // skipped as already-present: this is the standalone (manual/npm) channel
+  // only (the plugin channel never calls installHooks), and resolvePkgRoot()'s
+  // provenance fallback needs it to track the truth of what is actually on
+  // disk here, not just what a fresh copy left behind. See
+  // hooks/hypo-shared.mjs's readVerifiedProvenancePkgRoot() for the reader.
+  const sidecar = writeProvenanceSidecar(targetDir, PKG_ROOT, PKG_VERSION, HOOKS_SRC, dryRun);
+  if (sidecar) log('created', sidecar);
 }
 
 function mergeSettingsJson(settingsPath, hooksDir, dryRun, hookMap) {