hypomnema 1.7.1 → 1.7.3

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.3",
   "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/capture.mjs

@@ -42,9 +42,10 @@ import {
   unlinkSync,
   renameSync,
   realpathSync,
-  lstatSync,
   openSync,
   closeSync,
+  statSync,
+  chmodSync,
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { join, dirname, relative, sep } from 'path';
@@ -76,6 +77,7 @@ import {
   HOOK_EVENT_ALLOWLIST,
   SKILL_ROOT_FILE,
   EXT_PREFIX,
+  withSrcExecBits,
 } from './lib/extensions.mjs';
 import { readCoreHooksConfig, deriveCoreHookBasenames } from './lib/core-hooks.mjs';
 
@@ -582,7 +584,12 @@ function log(msg) {
 // `${dest}.tmp.${pid}` name was predictable, and writeFileSync on a path someone had
 // already planted a symlink at would follow it straight out of the wiki. O_EXCL fails
 // on an existing path of any kind, symlink included.
-function writeAtomic(dest, buf) {
+// `srcMode`, when given, carries the source file's execute bit onto the wiki
+// copy (openSync's own mode argument is clipped by umask same as writeFileSync,
+// so this still has to be a separate chmod). Omitted for a manifest write: that
+// content is JSON we generated, not a copy of something with a mode worth
+// keeping.
+function writeAtomic(dest, buf, srcMode) {
   const tmp = `${dest}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
   const fd = openSync(tmp, 'wx');
   try {
@@ -590,6 +597,9 @@ function writeAtomic(dest, buf) {
   } finally {
     closeSync(fd);
   }
+  if (srcMode != null) {
+    chmodSync(tmp, withSrcExecBits(statSync(tmp).mode, srcMode));
+  }
   try {
     renameSync(tmp, dest);
   } catch (err) {
@@ -719,7 +729,8 @@ function writeSkill({ rec, skillRoot, manifestPath, manifest, files, guard, wiki
         madeDirs.add(cur);
       }
     }
-    writeAtomic(destPath, readFileSync(f.srcPath));
+    const buf = readFileSync(f.srcPath);
+    writeAtomic(destPath, buf, statSync(f.srcPath).mode);
     rec.createdFiles.push(destPath);
   }
 }
@@ -814,22 +825,6 @@ function captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped,
     return;
   }
 
-  // Content round-trips; the executable bit does not (forward-sync writes with the
-  // default mode). Say so rather than let a captured `scripts/run.sh` arrive
-  // non-executable on the far machine without a word.
-  const execFiles = c.files.filter((f) => {
-    try {
-      return (lstatSync(f.srcPath).mode & 0o111) !== 0;
-    } catch {
-      return false;
-    }
-  });
-  if (execFiles.length > 0) {
-    log(
-      `! ${label}: ${execFiles.length} executable file(s) — content is captured, but the executable bit is not carried by sync`,
-    );
-  }
-
   if (!args.dryRun) {
     // The ledger is owned by the caller so a throw MID-write is still recoverable: the
     // paths created before the failure are already recorded in it.
@@ -1055,7 +1050,7 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
         manifestPrevBuf: existingManifestBuf,
       };
       writeAtomic(manifestPath, JSON.stringify(plan.manifest, null, 2) + '\n');
-      writeAtomic(filePath, srcBuf);
+      writeAtomic(filePath, srcBuf, statSync(c.srcPath).mode);
       created.push(rec);
     }
     captured.push({ ...c, installFile, requiredKeys, status: 'ready' });

package/scripts/crystallize.mjs

@@ -109,6 +109,7 @@ import {
   scopeVisible,
   readVisibilityScope,
   withFileLock,
+  extractTouchedWikiFilesWithTrust,
 } from '../hooks/hypo-shared.mjs';
 import { hashContent, readBaseEntry, advanceBase } from '../hooks/base-store.mjs';
 import { writeProposal } from '../hooks/proposal-store.mjs';
@@ -225,6 +226,35 @@ function requireProjectDir(args, slug) {
   }
 }
 
+// When the global gate's own discovery (hot.md pointer table + today
+// close-activity scan, both in hypo-shared.mjs) comes back with NO project at
+// all, a real apply never hits that dead end: it is handed `payload.project`
+// directly and never infers. --check-session-close has no payload, so its one
+// remaining authoritative signal is the same session's own transcript — which
+// project's files did THIS session actually touch. Reusing the exact
+// evidence-resolution helper the widened-lint-scope path already trusts here
+// keeps this a single inference vocabulary (touched wiki files), not a second
+// one: the difference is only which project-shaped question gets asked of it.
+// Never guessed: a transcript touching zero or more than one project's files
+// leaves the check exactly as unresolved as it was before this fallback.
+function deriveTouchedProject(hypoDir, transcriptPath) {
+  if (!transcriptPath) return null;
+  const { files, trusted } = extractTouchedWikiFilesWithTrust(transcriptPath, hypoDir);
+  // `trusted:false` means the walk itself may be incomplete (a missing/unreadable
+  // transcript, or a line that failed to parse). A truncated line could have named
+  // a SECOND project the walk never saw, so treating this Set as "the whole
+  // truth" would resolve a single-project reading off a scope that is only
+  // single-project because part of it is missing, exactly the ambiguity this
+  // fallback exists to refuse rather than guess through.
+  if (!trusted) return null;
+  const slugs = new Set();
+  for (const f of files) {
+    const m = /^projects\/([^/]+)\//.exec(f);
+    if (m && existsSync(join(hypoDir, 'projects', m[1]))) slugs.add(m[1]);
+  }
+  return slugs.size === 1 ? [...slugs][0] : null;
+}
+
 // ── session-close check (spec §5.2.7 / §8.3) ────────────────────────
 // Mirrors the hard gate in hypo-personal-check.mjs so the /hypo:crystallize
 // flow can self-verify before /compact triggers PreCompact.
@@ -261,7 +291,7 @@ function runSessionCloseCheck(args) {
     args.transcriptPath ||
     (args.sessionId ? resolveTranscriptBySessionId(args.sessionId) : null) ||
     null;
-  const status = precompactGateStatus(args.hypoDir, {
+  let status = precompactGateStatus(args.hypoDir, {
     ...(args.project
       ? { projectOverride: args.project }
       : checkTranscript
@@ -276,7 +306,30 @@ function runSessionCloseCheck(args) {
     // enforcement lives in the PreCompact/Stop hooks, which carry payload.cwd).
     ...(args.sessionCwd && !args.project ? { sessionCwd: args.sessionCwd } : {}),
   });
+
+  // check/apply divergence (2026-08-25 QA): a real apply never hits discovery
+  // dead-ends because payload.project is required input, not an inference. This
+  // check has no payload, so when discovery finds NO project at all (not even
+  // the recency fallback), it retries scoped to whatever single project this
+  // session's own transcript shows it touching. This is a diagnostic estimate,
+  // not a preview of what a real apply will do: a payload's `project` field is
+  // whatever the caller puts there and can legitimately name a project the
+  // transcript never mentions. Only fires on a fully unresolved global result,
+  // and only on a TRUSTED single-project reading (see deriveTouchedProject): an
+  // already-successful discovery, an ambiguous/empty transcript, or one the walk
+  // could not fully read is left untouched rather than guessed at.
+  let inferredProject = null;
+  if (!args.project && !status.close.project) {
+    inferredProject = deriveTouchedProject(args.hypoDir, checkTranscript);
+    if (inferredProject) {
+      status = precompactGateStatus(args.hypoDir, {
+        projectOverride: inferredProject,
+        ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+      });
+    }
+  }
   const close = status.close;
+  const scopedProject = args.project || inferredProject;
 
   // When a --session-id is supplied, report whether THIS session's
   // per-session marker (the Stop-chain completion signal) exists. This is a
@@ -301,8 +354,8 @@ function runSessionCloseCheck(args) {
   // log-only marker governs the session, the gate runs in log-only mode and the
   // --project override is IGNORED — surface that rather than implying X was
   // checked (it was not).
-  const logOnlyWon = args.project != null && markerObj?.scope === 'log-only';
-  const scope = args.project ? (logOnlyWon ? 'log-only' : 'project') : 'global';
+  const logOnlyWon = scopedProject != null && markerObj?.scope === 'log-only';
+  const scope = scopedProject ? (logOnlyWon ? 'log-only' : 'project') : 'global';
 
   if (args.json) {
     console.log(
@@ -325,9 +378,13 @@ function runSessionCloseCheck(args) {
           skipped: status.skipped,
           // scope is additive; `global` keeps prior semantics for existing readers
           scope,
-          ...(args.project
+          ...(scopedProject
             ? {
-                scoped_project: args.project,
+                scoped_project: scopedProject,
+                // Distinguishes a user-typed --project from this check picking one
+                // for itself off the transcript — a reader should not mistake the
+                // latter for an explicit ask (see deriveTouchedProject above).
+                ...(inferredProject ? { project_inferred_from_transcript: true } : {}),
                 ...(logOnlyWon ? { project_override_ignored: true } : {}),
               }
             : {}),
@@ -340,13 +397,20 @@ function runSessionCloseCheck(args) {
     process.exit(status.ok ? 0 : 1);
   }
 
+  // Label the scoped project by how it was chosen — an explicit --project reads
+  // as a flag the caller typed; an inferred one reads as this check's own guess
+  // off the transcript, so a reader does not credit the caller with an ask
+  // nobody made.
+  const scopedProjectLabel = args.project
+    ? `--project=${args.project}`
+    : `project=${scopedProject} (inferred from the session transcript, no --project given)`;
   if (logOnlyWon) {
     console.log(
-      `Note: a log-only session-closed marker governs session ${args.sessionId}, so the gate ran in log-only mode and --project=${args.project} was IGNORED (no project was checked).\n`,
+      `Note: a log-only session-closed marker governs session ${args.sessionId}, so the gate ran in log-only mode and ${scopedProjectLabel} was IGNORED (no project was checked).\n`,
     );
   } else if (scope === 'project') {
     console.log(
-      `Note: --project=${args.project} — this is a PROJECT-SCOPED diagnostic, not the global /compact gate. A green result means only ${args.project} is close-complete; another project can still block /compact.\n`,
+      `Note: ${scopedProjectLabel} — this is a PROJECT-SCOPED diagnostic, not the global /compact gate. A green result means only ${scopedProject} is close-complete; another project can still block /compact.\n`,
     );
   }
 
@@ -398,8 +462,8 @@ function runSessionCloseCheck(args) {
     // Do NOT claim global compact-readiness (the whole point of the narrow).
     console.log(
       status.ok
-        ? `✓ ${args.project} is close-complete (project-scoped). This is NOT a global /compact guarantee — run \`--check-session-close\` without --project for that.`
-        : `✗ ${args.project} is not close-complete — resolve the ✗ items above.`,
+        ? `✓ ${scopedProject} is close-complete (project-scoped). This is NOT a global /compact guarantee — run \`--check-session-close\` without --project for that.`
+        : `✗ ${scopedProject} is not close-complete — resolve the ✗ items above.`,
     );
   } else {
     console.log(
@@ -1043,7 +1107,10 @@ function applySessionClose(args) {
       stage: 'no-user-close-signal',
       reason: closeAuth.reason,
       applied: [],
-      committed: false,
+      // `null`, not `false`: this refusal fires before the commit step is ever
+      // reached (see the general result's own `committed` contract below).
+      // `false` is reserved for a commit that actually ran and failed.
+      committed: null,
       error: closeAuth.error,
     };
     console.log(
@@ -1103,7 +1170,9 @@ function applySessionClose(args) {
       stage: 'session-id-mismatch',
       error: msg,
       applied: [],
-      committed: false,
+      // `null`, not `false` — refused before the commit step, same contract as
+      // the `no-user-close-signal` refusal above.
+      committed: null,
     };
     console.log(args.json ? JSON.stringify(out, null, 2) : `✗ ${msg}`);
     process.exit(1);
@@ -1734,6 +1803,10 @@ function applySessionClose(args) {
   // but silently.
   let markerWritten = false;
   let markerSkipReason = null;
+  // Hoisted so the result JSON below can report it: `null` when this apply never
+  // reached the commit step at all (ok:false before the writes were even
+  // verified), distinct from a commit that ran and reported `committed:false`.
+  let commitOutcome = null;
   if (ok && args.sessionId) {
     // IO stays lazy so this preserves the exact side-effect order (codex design
     // review): commit first (the only mutation), then resolve the
@@ -1749,7 +1822,6 @@ function applySessionClose(args) {
     // apply's stage+commit. A lock-timeout is treated exactly like any other
     // commit failure below (skip the marker, surface the reason) rather than
     // crashing the apply.
-    let commitOutcome;
     try {
       commitOutcome = withFileLock(vaultCommitLockTarget(args.hypoDir), () =>
         commitWikiChanges(args.hypoDir, appliedPaths),
@@ -1843,6 +1915,19 @@ function applySessionClose(args) {
     date,
     applied,
     skipped,
+    // Was the general-shape sibling of the two early-refusal `committed:null`
+    // fields (no-user-close-signal / session-id-mismatch), which this path never
+    // carried before: a reader of `applied:[]` on a no-op re-run had no
+    // `committed` value to check against and no way to tell it apart from a run
+    // that never reached the commit step. `null` here means exactly that: `ok`
+    // came back false before the commit ever ran (see `stage` for which check
+    // failed: post-apply-verification, post-apply-lint, or proposal-pending). It
+    // does NOT mean nothing was written — an overwrite/append can already be on
+    // disk (see `applied` / `appliedUncommitted`) while `committed` stays `null`.
+    // `true` covers both an actual commit and the legitimate "nothing to stage"
+    // no-op (commitWikiChanges' own contract, see hooks/hypo-shared.mjs); `false`
+    // is a real commit failure, surfaced together with markerSkipReason below.
+    committed: commitOutcome ? commitOutcome.committed : null,
     // Targets withheld: an overwrite drifted from this session's observed base, or
     // an append could not take the file lock in time (`kind: 'append'`). Two
     // channels resolve these, and `proposals` vs `conflicts[].kind` are the sole

package/scripts/doctor.mjs

@@ -20,7 +20,7 @@ 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 { resolveGitHooksDir, WIKI_PRE_COMMIT_MARKER_START } from './lib/git-hooks-dir.mjs';
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import {
   readSyncState,
@@ -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) {
@@ -495,7 +506,7 @@ function checkGit(hypoDir) {
         ? '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')) {
+  } else if (content.includes(WIKI_PRE_COMMIT_MARKER_START)) {
     pass(label, 'Hypomnema .hypoignore guard installed');
   } else {
     warn(label, 'Exists but not managed by Hypomnema — manual git add can bypass .hypoignore');
@@ -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

@@ -38,7 +38,14 @@ import { execSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { expandHome, resolveHypoRoot } from './lib/hypo-root.mjs';
-import { hooksDirForInstall, unsafeHookTargetReason } from './lib/git-hooks-dir.mjs';
+import {
+  hooksDirForInstall,
+  unsafeHookTargetReason,
+  WIKI_PRE_COMMIT_MARKER_START,
+  WIKI_PRE_COMMIT_MARKER_END,
+  SHELL_MARKER_START,
+  SHELL_MARKER_END,
+} from './lib/git-hooks-dir.mjs';
 import { readCoreHooksConfig } from './lib/core-hooks.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
@@ -48,6 +55,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 +466,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) {
@@ -739,9 +755,6 @@ function installPkgGitHook(dryRun) {
 
 // ── wiki pre-commit hook ─────────────────────────────────────────────────────
 
-const WIKI_PRE_COMMIT_MARKER_START = '# hypo-managed:pre-commit:start';
-const WIKI_PRE_COMMIT_MARKER_END = '# hypo-managed:pre-commit:end';
-
 // Single-quote escaping prevents shell expansion of special chars (e.g. $HOME, backticks) in path
 function shellSingleQuote(p) {
   return `'${p.replace(/'/g, "'\\''")}'`;
@@ -850,9 +863,6 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
 
 // ── shell function setup ─────────────────────────────────────────────────────
 
-const SHELL_MARKER_START = '# hypo-managed:shell-setup:start';
-const SHELL_MARKER_END = '# hypo-managed:shell-setup:end';
-
 function shellFunctionBlock() {
   return `${SHELL_MARKER_START}
 function claude() {