hypomnema 1.7.1 → 1.7.3

package/scripts/lib/extensions.mjs

@@ -28,6 +28,8 @@ import {
   unlinkSync,
   mkdirSync,
   lstatSync,
+  statSync,
+  chmodSync,
   rmdirSync,
 } from 'fs';
 import { join, dirname, relative, resolve, posix, sep } from 'path';
@@ -894,9 +896,26 @@ export function readExtensionPkgStateNoMutate(pkgPath, target) {
 
 // ── sync orchestration ─────────────────────────────────────────────────────────
 
-function writeFreshAtomic(dest, content) {
+/** Carry only src's execute bits (owner/group/other) onto a mode value; every
+ * other permission bit (dest's own read/write, however umask shaped it) is
+ * left alone. This is the one place forward-sync decides "should this file be
+ * executable", so every writer of dest routes through it. Exported so
+ * capture.mjs's own atomic writer (a captured file's FIRST write into the wiki)
+ * applies the identical rule; the wiki copy must not lose the bit before
+ * forward-sync ever gets a chance to carry it further. */
+export function withSrcExecBits(destMode, srcMode) {
+  return (destMode & ~0o111) | (srcMode & 0o111);
+}
+
+function writeFreshAtomic(dest, content, srcMode) {
   const tmp = `${dest}.tmp.${process.pid}.${Date.now()}`;
   writeFileSync(tmp, content);
+  if (srcMode != null) {
+    // writeFileSync has no mode option that survives umask, so the execute bit
+    // has to be applied explicitly, and before the rename: otherwise dest is
+    // briefly visible with the wrong mode to anything racing this write.
+    chmodSync(tmp, withSrcExecBits(statSync(tmp).mode, srcMode));
+  }
   try {
     renameSync(tmp, dest);
   } catch (err) {
@@ -914,13 +933,19 @@ function writeFreshAtomic(dest, content) {
  * overwrites user-modified / unowned files; without it those are left untouched and
  * surface as drift/conflict. A symlink/non-regular dest is never followed even under
  * force (the isRegularFile guard precedes the force branch).
+ *
+ * The executable bit is not tracked anywhere (no mode column in the SHA map's
+ * ownership model), so src's mode is the only source of truth for it and gets
+ * carried onto dest on every branch that (re)writes it, including the
+ * content-identical `up-to-date` branch below.
  */
 function copyOne({ srcPath, destPath, key, recordedSHA, apply, force }) {
   const srcContent = readFileSync(srcPath);
   const srcSHA = sha256(srcContent);
+  const srcMode = statSync(srcPath).mode;
 
   if (!existsSync(destPath)) {
-    if (apply) writeFreshAtomic(destPath, srcContent);
+    if (apply) writeFreshAtomic(destPath, srcContent, srcMode);
     return { action: 'create', sha: srcSHA };
   }
   if (!isRegularFile(destPath)) {
@@ -933,6 +958,20 @@ function copyOne({ srcPath, destPath, key, recordedSHA, apply, force }) {
   }
   const onDiskSHA = sha256(onDisk);
   if (onDiskSHA === srcSHA) {
+    // Content already matches, but the exec bit can still be stale: this used to
+    // be a pure no-op, which is exactly why a mismatched bit here never healed.
+    // Reported as 'update' (not a new action) so every existing "N to sync" /
+    // "N synced" count and log line already keyed on create/update/force-update
+    // picks it up for free.
+    // ponytail: this also overwrites an exec bit a user deliberately flipped on a
+    // file whose content happens to still match src (chmod -x'd a script they
+    // like read-only). Upgrade path: record mode next to sha in the pkg-json map
+    // so a user's own bit can be told apart from our default and left alone.
+    const destMode = statSync(destPath).mode;
+    if ((destMode & 0o111) !== (srcMode & 0o111)) {
+      if (apply) chmodSync(destPath, withSrcExecBits(destMode, srcMode));
+      return { action: 'update', sha: srcSHA };
+    }
     return { action: 'up-to-date', sha: srcSHA };
   }
   if (recordedSHA && onDiskSHA === recordedSHA) {
@@ -942,7 +981,7 @@ function copyOne({ srcPath, destPath, key, recordedSHA, apply, force }) {
       if (!verify || sha256(verify) !== recordedSHA) {
         return { action: 'skip-changed', sha: recordedSHA };
       }
-      writeFreshAtomic(destPath, srcContent);
+      writeFreshAtomic(destPath, srcContent, srcMode);
     }
     return { action: 'update', sha: srcSHA };
   }
@@ -950,7 +989,7 @@ function copyOne({ srcPath, destPath, key, recordedSHA, apply, force }) {
   if (force) {
     if (apply) {
       writeFreshAtomic(`${destPath}.bak`, onDisk);
-      writeFreshAtomic(destPath, srcContent);
+      writeFreshAtomic(destPath, srcContent, srcMode);
     }
     return { action: 'force-update', sha: srcSHA };
   }

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

@@ -38,6 +38,16 @@ import { execFileSync } from 'child_process';
 import { existsSync, lstatSync, realpathSync, statSync } from 'fs';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'path';
 
+// ── shared install/uninstall markers ────────────────────────────────────────
+// init.mjs writes these when it installs the wiki's git pre-commit hook and
+// the shell rc block; uninstall.mjs reads them back to remove exactly what
+// init created. Defined once here, imported by both, so the two scripts can
+// never drift into recognizing different markers.
+export const WIKI_PRE_COMMIT_MARKER_START = '# hypo-managed:pre-commit:start';
+export const WIKI_PRE_COMMIT_MARKER_END = '# hypo-managed:pre-commit:end';
+export const SHELL_MARKER_START = '# hypo-managed:shell-setup:start';
+export const SHELL_MARKER_END = '# hypo-managed:shell-setup:end';
+
 // 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 = [

package/scripts/lib/pkg-provenance.mjs

@@ -0,0 +1,166 @@
+/**
+ * `.hypo-provenance.json` sidecar: copy-time producer proof for the
+ * standalone (manual/npm) hooks channel.
+ *
+ * hooks/hypo-shared.mjs's resolvePkgRoot() falls back to this file, verified
+ * against its own package name + a SHA-256 of the running hypo-shared.mjs,
+ * whenever self-location can't confirm a package root — the standalone hooks
+ * copy has no package.json alongside it to walk up to, by design (hooks
+ * import only Node built-ins, nothing outside the hooks dir).
+ *
+ * This is accidental-staleness protection, not a security boundary: any
+ * process running as this OS user can edit this JSON file freely, same as it
+ * could edit hooks/hypo-shared.mjs itself. It only guards against the
+ * accidental drift init/upgrade left unguarded before this fix — a hook
+ * file skip (already-present) that still let hypo-pkg.json's cached pointer
+ * move on to a newer version, silently mismatching the code actually copied.
+ *
+ * The filename and the producer-name check ("hypomnema") here must stay
+ * byte-identical with hooks/hypo-shared.mjs's own copy of this contract —
+ * hooks can't import scripts/, so the two sides are duplicated, not shared.
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'fs';
+import { join } from 'path';
+import { sha256 } from './pkg-json.mjs';
+import { readCoreHooksConfig, deriveCoreHookBasenames } from './core-hooks.mjs';
+
+export const PROVENANCE_FILENAME = '.hypo-provenance.json';
+export const EXPECTED_PKG_NAME = 'hypomnema';
+
+// Field name for the aggregate hook-set hash (BLOCKER A). Exported so
+// scripts/doctor.mjs reads/writes the same key instead of duplicating the
+// string literal — doctor already imports this module for
+// PROVENANCE_FILENAME/EXPECTED_PKG_NAME, so importing one more constant costs
+// nothing and closes the duplication CONCERN 1 flagged for the filename/name
+// pair (those two stay duplicated only because hooks/hypo-shared.mjs can't
+// import this file at all).
+export const HOOKS_DIGEST_FIELD = 'hooksDigest';
+
+/**
+ * Deterministic aggregate hash over every hook file hooks/hooks.json wires up
+ * (every event handler's file plus every `shared` entry) — the exact set
+ * installHooks/applyHookFiles copy, derived from hooks.json itself rather
+ * than hand-listed here so this can never drift from what actually gets
+ * copied. `dir` is read for CONTENT: pass hooksSrcDir at write time (the
+ * package's own hooks/, immediately after files were copied out of it — see
+ * writeProvenanceSidecar) and the installed hooksDir at doctor-check time
+ * (mirrors how hypoSharedSha256 below is written from source but verified
+ * against the installed copy).
+ *
+ * Deliberately NOT what the runtime resolver reads: hooks/hypo-shared.mjs's
+ * readVerifiedProvenancePkgRoot() only ever compares hypoSharedSha256, one
+ * file, because hook modules load on every single hook event and hashing an
+ * entire directory on every load would tax the hot path for a check only
+ * `hypomnema doctor` needs to run once per invocation. This digest is that
+ * doctor-only, directory-wide check: it catches a hooks/ dir where some OTHER
+ * file (e.g. hypo-personal-check.mjs) went stale while hypo-shared.mjs itself
+ * stayed byte-identical, which the single-file SHA the runtime trusts cannot
+ * see at all.
+ *
+ * Sorted basenames, `<file>\n<sha256-of-file-hex>\n` per file concatenated,
+ * then SHA-256 of that string — order and content only, never mtime/size.
+ * Returns null if hooks.json can't be read/parsed or any listed file can't be
+ * read, so a caller can treat "couldn't compute" the same as "nothing to
+ * compare" rather than writing/trusting a bogus digest.
+ */
+export function computeHooksDigest(pkgRoot, dir) {
+  const cfgRes = readCoreHooksConfig(pkgRoot);
+  if (!cfgRes.ok) return null;
+  const files = [...deriveCoreHookBasenames(cfgRes.cfg)].sort();
+  try {
+    let acc = '';
+    for (const file of files) {
+      acc += `${file}\n${sha256(readFileSync(join(dir, file)))}\n`;
+    }
+    return sha256(acc);
+  } catch {
+    return null;
+  }
+}
+
+export function provenancePath(hooksDir) {
+  return join(hooksDir, PROVENANCE_FILENAME);
+}
+
+/**
+ * Write/refresh the sidecar next to a standalone hooks copy at `hooksDir`.
+ * `hooksSrcDir` is the package's own hooks/ (the source hypo-shared.mjs was
+ * just copied FROM) — its content is what gets hashed, since that hash is
+ * what the copy left at `hooksDir` will actually match.
+ *
+ * Callers must invoke this every run that touches — or even just re-verifies
+ * — the hook file set, EVEN when every individual .mjs file was skipped as
+ * already-present. A skipped hook copy that still lets hypo-pkg.json's
+ * pkgVersion move on to a newer release is exactly the bug this sidecar
+ * exists to catch; refreshing it only when files actually changed would
+ * reintroduce that gap under a new name.
+ *
+ * Returns the sidecar path written, or null if the source couldn't be
+ * hashed (leaves any pre-existing sidecar untouched rather than write a
+ * broken one).
+ *
+ * `hooksDigest` (BLOCKER A) is best-effort: computed from the same
+ * `hooksSrcDir`, over the file set hooks.json actually wires up. Unlike
+ * hypoSharedSha256 above, a failure to compute it does not abort the write —
+ * it is a doctor-only freshness signal, not part of the runtime contract
+ * (hooks/hypo-shared.mjs never reads this field), so a sidecar the runtime
+ * can verify should not be withheld just because the digest step failed.
+ */
+export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDir, dryRun) {
+  let hypoSharedSha256;
+  try {
+    hypoSharedSha256 = sha256(readFileSync(join(hooksSrcDir, 'hypo-shared.mjs')));
+  } catch {
+    return null;
+  }
+  const hooksDigest = computeHooksDigest(pkgRoot, hooksSrcDir);
+  const dest = provenancePath(hooksDir);
+  const data = {
+    pkgRoot,
+    pkgVersion,
+    hypoSharedSha256,
+    ...(hooksDigest ? { [HOOKS_DIGEST_FIELD]: hooksDigest } : {}),
+    copiedAt: new Date().toISOString(),
+  };
+  if (!dryRun) atomicWriteJson(dest, data);
+  return dest;
+}
+
+// Tmp file in the SAME directory as `dest`, then rename over it (CONCERN 2):
+// a reader (readVerifiedProvenancePkgRoot in hooks/hypo-shared.mjs) that
+// races a plain truncate-then-write can observe a half-written file and
+// JSON.parse throws, degrading PKG_ROOT to null for that hook invocation.
+// Same directory is required for the rename to be atomic — crossing a
+// filesystem boundary would fall back to a non-atomic copy+delete.
+function atomicWriteJson(dest, data) {
+  const tmp = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  try {
+    renameSync(tmp, dest);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+/** Remove the sidecar at `hooksDir`, if present. Returns the path removed, or null. */
+export function removeProvenanceSidecar(hooksDir, apply) {
+  const dest = provenancePath(hooksDir);
+  if (!existsSync(dest)) return null;
+  if (apply) unlinkSync(dest);
+  return dest;
+}
+
+/** Non-mutating read. Returns the parsed sidecar, or null on absence/corruption. */
+export function readProvenanceSidecar(hooksDir) {
+  try {
+    return JSON.parse(readFileSync(provenancePath(hooksDir), 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/scripts/lint.mjs

@@ -19,7 +19,7 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
 import { join, extname, basename } from 'path';
 import { resolveHypoRootInfo, checkVaultOrExit, expandHome } from './lib/hypo-root.mjs';
-import { SESSION_STATE_NEXT_HEADINGS } from '../hooks/hypo-shared.mjs';
+import { SESSION_STATE_NEXT_HEADINGS, closeFileTargetsGlobal } from '../hooks/hypo-shared.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 import {
   parseSchemaVocab,
@@ -554,6 +554,50 @@ const validTypes = new Set([...VALID_TYPES, ...parseSchemaTypes(args.hypoDir)]);
 
 for (const page of pages) lintPage(page, slugMap, tagVocab, pageDirs, validTypes);
 
+// W4 (broken-wikilink only, NOT the full lintPage) for close's root-level
+// write targets that fall outside pages/projects/journal: hot.md and log.md
+// today. closeFileTargetsGlobal is the one list of what close writes
+// (hooks/hypo-shared.mjs), reused here instead of re-derived, so a future
+// close target is covered automatically. Only the entries NOT already under
+// a scanDir are new; closeFileTargetsGlobal's projects/<slug>/* entries are
+// already linted in full above.
+//
+// Why link-only and not the full lintPage: measured, not assumed. On the
+// packaged templates/ (hot.md type:reference, log.md type:log, both declared
+// in templates/SCHEMA.md's taxonomy), full lintPage on both files comes back
+// completely clean, so "these types trip W2" is not the reason to hold back.
+// The real reason is that live vaults do not all match the template. A vault
+// whose SCHEMA.md predates the `log` type row (or has none) gets a fresh
+// "Unknown type: log" W2 the moment log.md is run through lintPage, and a
+// vault whose root log.md predates the frontmatter convention entirely (no
+// leading `---` block at all, confirmed against a real maintainer vault)
+// gets a fresh "No frontmatter found" W1. Both W1 and W2 are in
+// STRICT_PROMOTE_IDS, so under --strict a vault that lint has always passed
+// would start failing on a file whose content this fix never touched. Full
+// lintPage stays reserved for pages/projects/journal, where every file was
+// already being linted before this change and there is no such newly-exposed
+// vault. W4 itself stays warn-only outside --strict, and postApply
+// (crystallize.mjs) gates only on errors, so this addition can add a new
+// warning to a close's lint output but can never fail one.
+const closeRootTargets = [...closeFileTargetsGlobal(args.hypoDir)].filter(
+  (f) => !f.startsWith('pages/') && !f.startsWith('projects/') && !f.startsWith('journal/'),
+);
+for (const rel of closeRootTargets) {
+  const full = join(args.hypoDir, rel);
+  if (!existsSync(full) || isScanIgnored(full, args.hypoDir, ignorePatterns)) continue;
+  let content;
+  try {
+    content = readFileSync(full, 'utf-8');
+  } catch {
+    continue;
+  }
+  for (const link of extractWikilinks(content)) {
+    if (!slugMap.has(link)) {
+      issue('warn', rel, `Broken wikilink: [[${link}]]`, null, 'W4');
+    }
+  }
+}
+
 // W8: design-history.md stale relative to session-log.md. Emitted once per
 // project (not per page) — runs outside the page loop. POSIX-separated path
 // literal (not path.join) so consumers can rely on `file.split('/')` shape

package/scripts/uninstall.mjs

@@ -14,6 +14,15 @@
  *   --force-commands     Remove user-modified slash commands instead of preserving them
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
+ *   --hypo-dir=<path>    Wiki vault to remove the pre-commit hook from (default: auto-resolve,
+ *                        same rules as init/lint/query)
+ *   --shell-config=<path> Shell rc file to strip the shell block from (default: checks both
+ *                        ~/.zshrc and ~/.bashrc, since init may have run under either shell)
+ *
+ * The wiki's git pre-commit hook and the shell rc's `claude()` wrapper function are removed
+ * only when they still carry the marker init.mjs wrote (WIKI_PRE_COMMIT_MARKER_START /
+ * SHELL_MARKER_START, both from ./lib/git-hooks-dir.mjs). A user's own pre-commit hook, a
+ * symlinked hook target, and any rc content outside the marker block are never touched.
  *
  * Extensions: hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
@@ -23,7 +32,16 @@
  * does not follow them). The wiki source (~/hypomnema/extensions/) is preserved.
  */
 
-import { existsSync, readFileSync, writeFileSync, rmSync, rmdirSync, readdirSync } from 'fs';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  rmdirSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+} from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
@@ -47,6 +65,16 @@ import {
   hasSymlinkAncestor,
   buildHookCommand,
 } from './lib/extensions.mjs';
+import { removeProvenanceSidecar } from './lib/pkg-provenance.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 { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -427,6 +455,182 @@ function stripExtensionSettings(settingsPath, hooksDir, apply, ownedCommands = n
   return { stripped };
 }
 
+// ── marker-span validation (shared by both removal paths below) ────────────
+
+// Two independent indexOf() calls cannot tell "well-formed" apart from
+// "duplicated" or "swapped": if a file happens to hold two full copies of the
+// block, indexOf finds only the first END, so slicing [firstStart, firstEnd]
+// leaves the second copy's install behind with no report of it. If END
+// precedes START (a hand-edited or corrupted file), slicing [start, end) with
+// start > end does not error, it silently duplicates whatever sits between
+// them into the "removed" span. Neither this script nor the file it is
+// touching has a way back from either outcome, so a span is only trusted when
+// both markers appear EXACTLY once and START comes before END.
+function countOccurrences(content, needle) {
+  let count = 0;
+  let idx = 0;
+  while ((idx = content.indexOf(needle, idx)) !== -1) {
+    count++;
+    idx += needle.length;
+  }
+  return count;
+}
+
+function findMarkerSpan(content, startMarker, endMarker) {
+  const startCount = countOccurrences(content, startMarker);
+  const endCount = countOccurrences(content, endMarker);
+  if (startCount !== 1 || endCount !== 1) {
+    return {
+      ok: false,
+      reason: `expected exactly one start and one end marker, found ${startCount} start / ${endCount} end`,
+    };
+  }
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (!(startIdx < endIdx)) {
+    return { ok: false, reason: 'the end marker appears before the start marker' };
+  }
+  return { ok: true, startIdx, endIdx };
+}
+
+// ── wiki pre-commit hook removal ────────────────────────────────────────────
+
+// Mirrors init.mjs's own resolution (hooksDirForInstall) as the PRIMARY
+// candidate, so this finds the hook wherever init would put it today,
+// including under a core.hooksPath override. A second, best-effort candidate
+// (the vault's plain .git/hooks/pre-commit) is checked too: if core.hooksPath
+// changed after install, the current resolution no longer points at the file
+// init actually wrote, and that file would otherwise never be found. Both
+// candidates go through the same marker/ownership gate below, so widening the
+// search costs nothing in safety, only in how many places we bother to look.
+// A hook that still carries our marker is removed; a user's own pre-commit (no
+// marker), a symlinked/non-regular target, and a hook whose marker is
+// duplicated, swapped, or missing its shebang are all left standing.
+// `pre-commit.bak` (init's --force-commands backup of the user's original
+// hook) is never removed here, only reported so the user knows it exists.
+function removeWikiPreCommitHook(hypoDir, apply) {
+  const result = { removed: [], skipped: [], bakPresent: [] };
+
+  if (!hypoDir || !existsSync(join(hypoDir, 'hypo-config.md'))) {
+    result.skipped.push(`no Hypomnema vault found${hypoDir ? ` at ${hypoDir}` : ''} — nothing to remove`);
+    return result;
+  }
+
+  const candidateDirs = [];
+  const { dir: hooksDir, skip } = hooksDirForInstall(hypoDir);
+  if (hooksDir) candidateDirs.push(hooksDir);
+  else if (skip) result.skipped.push(skip);
+
+  // Best-effort fallback: only when `.git` is a real directory here (a plain
+  // checkout, not a linked worktree's gitdir-pointer FILE, which this join
+  // would misread entirely — resolveGitHooksDir already handles that layout
+  // correctly via the primary candidate above).
+  const legacyGitDir = join(hypoDir, '.git');
+  if (existsSync(legacyGitDir) && statSync(legacyGitDir).isDirectory()) {
+    candidateDirs.push(join(legacyGitDir, 'hooks'));
+  }
+
+  const seen = new Set();
+  for (const dir of candidateDirs) {
+    const hookPath = join(dir, 'pre-commit');
+    // Dedupe by the resolved real path, not the string: the primary candidate
+    // is realpath'd internally (resolveGitHooksDir's canonicalize) while the
+    // legacy join above is not, so the same physical file can arrive under two
+    // different-looking paths. Falling back to the raw path when the file does
+    // not exist is fine — two distinct absent candidates never collide.
+    let key = hookPath;
+    try {
+      key = realpathSync(hookPath);
+    } catch {
+      // leave key as hookPath
+    }
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const bakPath = `${hookPath}.bak`;
+    if (existsSync(bakPath)) result.bakPresent.push(bakPath);
+
+    const unsafe = unsafeHookTargetReason(hookPath);
+    if (unsafe) {
+      result.skipped.push(`${hookPath} (${unsafe})`);
+      continue;
+    }
+    if (!existsSync(hookPath)) continue; // already absent, nothing to report
+
+    let content;
+    try {
+      content = readFileSync(hookPath, 'utf-8');
+    } catch (e) {
+      result.skipped.push(`${hookPath} (cannot read: ${e.code || e.message})`);
+      continue;
+    }
+    if (!content.includes(WIKI_PRE_COMMIT_MARKER_START) || !content.includes(WIKI_PRE_COMMIT_MARKER_END)) {
+      result.skipped.push(`${hookPath} (not managed by Hypomnema — preserving)`);
+      continue;
+    }
+
+    const span = findMarkerSpan(content, WIKI_PRE_COMMIT_MARKER_START, WIKI_PRE_COMMIT_MARKER_END);
+    if (!span.ok) {
+      result.skipped.push(`${hookPath} (${span.reason} — preserving)`);
+      continue;
+    }
+
+    // init writes the marker as the ENTIRE hook body: a bare "#!/bin/sh\n"
+    // right before WIKI_PRE_COMMIT_MARKER_START, nothing after
+    // WIKI_PRE_COMMIT_MARKER_END. A file with no shebang there was never
+    // written by init even if it happens to carry a well-formed marker span
+    // (hand-authored or copy-pasted) — deleting it on marker presence alone
+    // would remove code we do not own. A user who appended their own check
+    // after the block turned this into a file we only partly own. init's own
+    // --force-commands path handles the analogous case by OVERWRITING with
+    // equivalent content (a safe merge); uninstall has no such repair, only
+    // rmSync, so treating "extra content" the same as "fully ours" would
+    // silently delete the user's check with no way back.
+    const before = content.slice(0, span.startIdx);
+    const after = content.slice(span.endIdx + WIKI_PRE_COMMIT_MARKER_END.length);
+    if (!/^#![^\n]*\n$/.test(before)) {
+      result.skipped.push(`${hookPath} (hook carries content before the Hypomnema block — preserving)`);
+      continue;
+    }
+    if (after.trim() !== '') {
+      result.skipped.push(`${hookPath} (hook carries content after the Hypomnema block — preserving)`);
+      continue;
+    }
+
+    if (apply) rmSync(hookPath);
+    result.removed.push(hookPath);
+  }
+
+  return result;
+}
+
+// ── shell function block removal ────────────────────────────────────────────
+
+// init picks ONE rc file at install time from $SHELL (or --shell-config), but
+// $SHELL by uninstall time may point somewhere else, or init may have run in
+// a different shell session altogether — so both common rc files are checked
+// by default rather than guessing one. Only the marker span itself is
+// stripped; every other byte in the file, including surrounding blank lines,
+// is left exactly as it was. A malformed span (duplicated or swapped markers,
+// see findMarkerSpan above) leaves the file completely untouched: an rc file
+// is the user's own, and this script has no backup to restore it from.
+function removeShellFunctionBlock(shellConfigPath, apply) {
+  if (!existsSync(shellConfigPath)) return null;
+  const content = readFileSync(shellConfigPath, 'utf-8');
+  if (!content.includes(SHELL_MARKER_START) && !content.includes(SHELL_MARKER_END)) {
+    return null; // block not present here at all
+  }
+
+  const span = findMarkerSpan(content, SHELL_MARKER_START, SHELL_MARKER_END);
+  if (!span.ok) {
+    return { path: shellConfigPath, removed: false, skipped: span.reason };
+  }
+
+  const updated = content.slice(0, span.startIdx) + content.slice(span.endIdx + SHELL_MARKER_END.length);
+  if (apply) writeFileSync(shellConfigPath, updated);
+  return { path: shellConfigPath, removed: true, skipped: null };
+}
+
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -436,6 +640,8 @@ function parseArgs(argv) {
     hooksDir: null,
     forceCommands: false,
     forceExtensions: false,
+    hypoDir: null,
+    shellConfig: null,
   };
   for (const arg of argv.slice(2)) {
     if (arg === '--apply') args.apply = true;
@@ -443,6 +649,16 @@ function parseArgs(argv) {
     else if (arg === '--force-commands') args.forceCommands = true;
     else if (arg === '--force-extensions') args.forceExtensions = true;
     else if (arg.startsWith('--hooks-dir=')) args.hooksDir = arg.slice(12);
+    // expandHome mirrors init.mjs's own --hypo-dir/--shell-config parsing
+    // (init.mjs's parseArgs) exactly, reusing the same function from
+    // ./lib/hypo-root.mjs rather than re-deriving it. Uninstall must undo
+    // whatever path init actually wrote to disk, and init resolves a leading
+    // "~/" itself (the shell never does, since the value arrives already
+    // quoted inside "--flag=value"); skipping that step here would silently
+    // fail to find the vault or rc file a user installed with "~/..." to
+    // begin with.
+    else if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--shell-config=')) args.shellConfig = expandHome(arg.slice(15));
   }
   return args;
 }
@@ -510,6 +726,17 @@ function removeHookFiles(hooksDir, hookFiles, apply) {
       missing.push(p);
     }
   }
+  // .hypo-provenance.json (scripts/lib/pkg-provenance.mjs) is written next to
+  // this exact hooksDir by installHooks/applyHookFiles — same lifecycle as the
+  // hook files themselves, so it is removed in the same pass rather than left
+  // behind to describe a package root that no longer has any hooks pointing
+  // through it. Unlike hookFiles above, this is an optional file (only the
+  // manual/npm channel ever writes one) — so, mirroring the loop's own
+  // present/absent split, it is only added to `removed` (dry-run: "to remove")
+  // when it actually exists; a channel that never wrote one gets no line at
+  // all, not a spurious "already absent".
+  const sidecar = removeProvenanceSidecar(hooksDir, apply);
+  if (sidecar) removed.push(sidecar);
   return { removed, missing };
 }
 
@@ -577,6 +804,20 @@ const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
 const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
+// Wiki-side cleanup: the git pre-commit hook and the shell rc block init.mjs
+// installs outside ~/.claude entirely. Both are independent of --codex/--hooks-dir.
+const hypoDir = args.hypoDir ?? resolveHypoRoot();
+const preCommitResult = removeWikiPreCommitHook(hypoDir, args.apply);
+
+const shellConfigCandidates = args.shellConfig
+  ? [args.shellConfig]
+  : [join(HOME, '.zshrc'), join(HOME, '.bashrc')];
+const shellBlockOutcomes = shellConfigCandidates
+  .map((p) => removeShellFunctionBlock(p, args.apply))
+  .filter(Boolean);
+const shellBlockResults = shellBlockOutcomes.filter((r) => r.removed).map((r) => r.path);
+const shellBlockSkipped = shellBlockOutcomes.filter((r) => !r.removed);
+
 // Extensions. Order matters: remove files first, then strip
 // settings, then surgically clear the per-target SHA map. The SHA strip uses
 // removedKeys so a user-modified file we left in place keeps its recorded SHA
@@ -724,6 +965,27 @@ if (hookResult.missing.length)
   lines.push(
     `⊘ Already absent (${hookResult.missing.length}):\n${hookResult.missing.map((p) => `  ${p}`).join('\n')}`,
   );
+if (preCommitResult.removed.length)
+  lines.push(
+    `✓ Wiki pre-commit hook ${dryRun ? 'to remove' : 'removed'} (${preCommitResult.removed.length}):\n${preCommitResult.removed.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (preCommitResult.skipped.length)
+  lines.push(
+    `⊘ Wiki pre-commit hook preserved:\n${preCommitResult.skipped.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (preCommitResult.bakPresent.length)
+  lines.push(
+    `ⓘ Pre-commit backup left in place (from --force-commands, never touched by uninstall):\n${preCommitResult.bakPresent.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (shellBlockResults.length)
+  lines.push(
+    `✓ Shell function block ${dryRun ? 'to remove' : 'removed'} (${shellBlockResults.length}):\n${shellBlockResults.map((p) => `  ${p}`).join('\n')}`,
+  );
+if (shellBlockSkipped.length)
+  lines.push(
+    `⊘ Shell function block preserved:\n${shellBlockSkipped.map((r) => `  ${r.path} (${r.skipped})`).join('\n')}`,
+  );
+
 if (settingsResult.error) lines.push(`⚠ ${settingsResult.error}`);
 if (claudeExtSettings.error) lines.push(`⚠ ${claudeExtSettings.error}`);
 if (codexExtSettings.error) lines.push(`⚠ ${codexExtSettings.error}`);
@@ -738,7 +1000,9 @@ if (
   !pkgJsonRemoved &&
   !commandResult.skippedUserModified.length &&
   !extSkippedUserModified.length &&
-  !extSkippedNonRegular.length
+  !extSkippedNonRegular.length &&
+  !preCommitResult.removed.length &&
+  !shellBlockResults.length
 ) {
   lines.push('Nothing to uninstall — Hypomnema does not appear to be installed.');
 }