hypomnema 1.7.3 → 1.7.4

package/scripts/capture.mjs

@@ -45,7 +45,8 @@ import {
   openSync,
   closeSync,
   statSync,
-  chmodSync,
+  fstatSync,
+  fchmodSync,
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { join, dirname, relative, sep } from 'path';
@@ -589,17 +590,27 @@ function log(msg) {
 // 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.
+//
+// The mode is set on the open FD (`fchmodSync`), before the FD is closed, the
+// same ordering the forward writer (extensions.mjs's writeFreshAtomic) already
+// uses. A pathname-based `chmodSync(tmp, ...)` run after `closeSync` reopens
+// `tmp` by name, and a competing process racing this write could have already
+// deleted `tmp` and planted a symlink at that name in the gap between close
+// and chmod — `wx` only protects the file's creation, not everything after it.
+// Chmod-ing the FD closes that window: it always addresses the file this
+// process itself just created, never whatever a symlink at the same name
+// might point to by the time the pathname is looked up again.
 function writeAtomic(dest, buf, srcMode) {
   const tmp = `${dest}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
   const fd = openSync(tmp, 'wx');
   try {
     writeFileSync(fd, buf);
+    if (srcMode != null) {
+      fchmodSync(fd, withSrcExecBits(fstatSync(fd).mode, srcMode));
+    }
   } finally {
     closeSync(fd);
   }
-  if (srcMode != null) {
-    chmodSync(tmp, withSrcExecBits(statSync(tmp).mode, srcMode));
-  }
   try {
     renameSync(tmp, dest);
   } catch (err) {

package/scripts/crystallize.mjs

@@ -102,7 +102,7 @@ import {
   hasSessionLogHeading,
   hasLogEntry,
   resolveTranscriptBySessionId,
-  hasUserCloseSignal,
+  isCloseGateOpen,
   commitWikiChanges,
   vaultCommitLockTarget,
   currentDevice,
@@ -113,6 +113,7 @@ import {
 } from '../hooks/hypo-shared.mjs';
 import { hashContent, readBaseEntry, advanceBase } from '../hooks/base-store.mjs';
 import { writeProposal } from '../hooks/proposal-store.mjs';
+import { recordGateClosed, resolutionStamp, closeGateStatus } from '../hooks/close-gate-store.mjs';
 
 // This script's own absolute path. Used to print copy-pasteable recovery
 // commands as `node <SELF_SCRIPT> ...` rather than a bare `crystallize` bin,
@@ -750,7 +751,7 @@ function runMarkSessionClosed(args) {
   // /compact, or an AskUserQuestion close answer). This is the hard backstop for
   // model over-close, where prose guidance lost to a conflicting global rule.
   // Fail-closed when the transcript can't be resolved.
-  if (!closeTranscript || !hasUserCloseSignal(closeTranscript)) {
+  if (!closeTranscript || !isCloseGateOpen(closeTranscript)) {
     const reason = !closeTranscript
       ? `cannot resolve a transcript for session ${args.sessionId} — the session-closed marker requires a verifiable user close signal`
       : "no user close signal in this session's transcript — marker refused (the user did not signal session close)";
@@ -938,7 +939,7 @@ const CLOSE_REFUSAL_HELP = [
  *   { ok: false, reason, error }   reason: session-id-required | transcript-unresolved
  *                                          | no-user-close-signal
  */
-function verifyCloseAuthority(sessionId) {
+function verifyCloseAuthority(sessionId, hypoDir) {
   if (!sessionId) {
     return {
       ok: false,
@@ -961,13 +962,15 @@ function verifyCloseAuthority(sessionId) {
         `authority here.`,
     };
   }
-  if (!hasUserCloseSignal(transcript)) {
+  const gateStatus = closeGateStatus({ transcriptPath: transcript, hypoDir, sessionId });
+  if (!gateStatus.ok) {
     return {
       ok: false,
       reason: 'no-user-close-signal',
       error:
         "session-close apply refused before any wiki write or commit: this session's transcript " +
-        'carries no user close signal. The user did not ask to close.',
+        'carries no user close signal. The user did not ask to close. ' +
+        `Gate detail: ${gateStatus.reason}`,
     };
   }
   return { ok: true };
@@ -1100,7 +1103,9 @@ function applySessionClose(args) {
   // Only a payload-bearing call can write. A payload-less one falls through to the
   // "payload is required" error below without touching a byte, so gating it here
   // would just replace one refusal with a less accurate one.
-  const closeAuth = args.payload ? verifyCloseAuthority(args.sessionId) : { ok: true };
+  const closeAuth = args.payload
+    ? verifyCloseAuthority(args.sessionId, args.hypoDir)
+    : { ok: true };
   if (!closeAuth.ok) {
     const out = {
       ok: false,
@@ -1808,6 +1813,39 @@ function applySessionClose(args) {
   // verified), distinct from a commit that ran and reported `committed:false`.
   let commitOutcome = null;
   if (ok && args.sessionId) {
+    // Close-gate resolution: apply succeeding (`ok`) IS the resolution, not
+    // whether the per-session marker below happens to land. The marker can
+    // be withheld for reasons that have nothing to do with whether this
+    // apply's own writes were valid (a stale git tree, a feedback-projection
+    // cap, W8 design-history staleness) — none of that should leave the
+    // resolution unrecorded, because the wiki writes already happened, and
+    // re-running the SAME apply with no fresh user close signal is exactly
+    // what this record exists to block. So this sits OUTSIDE and ahead of
+    // the marker's own commit-gated logic below, resolving its own
+    // transcript rather than sharing the marker's `closeTranscript` (which
+    // stays null whenever the commit fails) — a commit failure withholds
+    // the marker but must not also withhold the resolution.
+    //
+    // Best-effort like every other write in this store: resolutionStamp
+    // returns null on anything it cannot read as a Buffer, recordGateClosed
+    // refuses a null stamp, and both fail silently, so a transcript that
+    // vanishes mid-read (or a cache-write failure) can never turn an
+    // otherwise-successful apply into a failure.
+    try {
+      const resolutionTranscriptPath = resolveTranscriptBySessionId(args.sessionId);
+      if (resolutionTranscriptPath) {
+        recordGateClosed(
+          args.hypoDir,
+          args.sessionId,
+          resolutionStamp(readFileSync(resolutionTranscriptPath)),
+        );
+      }
+    } catch {
+      // Unreadable at the moment of a successful close is not this apply's
+      // problem to surface — the resolution just stays unrecorded, same as
+      // if this session had never resolved at all (NO_CONSTRAINT).
+    }
+
     // IO stays lazy so this preserves the exact side-effect order (codex design
     // review): commit first (the only mutation), then resolve the
     // transcript, then run the compact gate with that transcript, then scan the
@@ -1851,8 +1889,18 @@ function applySessionClose(args) {
       gateOk,
       transcriptResolved: !!closeTranscript,
       // Scan the signal only when the gate passed AND a transcript resolved —
-      // hasUserCloseSignal never runs earlier than the original nested `else if`.
-      hasUserSignal: gateOk && !!closeTranscript && hasUserCloseSignal(closeTranscript),
+      // isCloseGateOpen never runs earlier than the original nested `else if`.
+      // Reads the raw walkCloseGate open, not closeGateStatus: this apply's
+      // OWN recordGateClosed call above already ran with this transcript's
+      // full record count as closedAtIndex, and openedAtIndex can never reach
+      // or pass a count taken from the very same transcript (see
+      // closeGateStatus's doc comment) — so gating this diagnostic on .ok
+      // would read false on every apply, unconditionally, not just a stale
+      // one. This field asks a narrower question than closeGateStatus
+      // answers: "did the transcript carry a close signal", not "is this
+      // apply itself still authorized" (verifyCloseAuthority already settled
+      // that, before any byte was written).
+      hasUserSignal: gateOk && !!closeTranscript && isCloseGateOpen(closeTranscript),
     });
     markerSkipReason = decision.skipReason;
     if (decision.write) {

package/scripts/init.mjs

@@ -41,10 +41,12 @@ import { expandHome, resolveHypoRoot } from './lib/hypo-root.mjs';
 import {
   hooksDirForInstall,
   unsafeHookTargetReason,
+  findMarkerSpan,
   WIKI_PRE_COMMIT_MARKER_START,
   WIKI_PRE_COMMIT_MARKER_END,
   SHELL_MARKER_START,
   SHELL_MARKER_END,
+  SHELL_FUNCTION_BODY,
 } from './lib/git-hooks-dir.mjs';
 import { readCoreHooksConfig } from './lib/core-hooks.mjs';
 import {
@@ -863,13 +865,13 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
 
 // ── shell function setup ─────────────────────────────────────────────────────
 
+// Built FROM SHELL_FUNCTION_BODY (./lib/git-hooks-dir.mjs), not a second copy
+// of the same literal: uninstall's isOwnedShellFunctionBody() compares an
+// existing marker span's body against that same constant byte-for-byte, so
+// this and that check can never drift apart the way two independent string
+// literals could.
 function shellFunctionBlock() {
-  return `${SHELL_MARKER_START}
-function claude() {
-  echo "{\\"cwd\\":\\"$(pwd)\\"}" | node "$HOME/.claude/hooks/hypo-session-start.mjs" > /dev/null 2>&1
-  command claude "$@"
-}
-${SHELL_MARKER_END}`;
+  return `${SHELL_MARKER_START}${SHELL_FUNCTION_BODY}${SHELL_MARKER_END}`;
 }
 
 function detectShellConfig(customPath) {
@@ -892,19 +894,32 @@ function installShellFunction(shellConfigPath, dryRun) {
   }
 
   const content = readFileSync(shellConfigPath, 'utf-8');
-  const startIdx = content.indexOf(SHELL_MARKER_START);
-  const endIdx = content.indexOf(SHELL_MARKER_END);
 
-  if (startIdx !== -1 && endIdx !== -1) {
+  if (content.includes(SHELL_MARKER_START) || content.includes(SHELL_MARKER_END)) {
+    // A block-shaped span is claimed here: validate it the same way uninstall
+    // does before touching a single byte. Two bare indexOf() calls cannot tell
+    // "well-formed" apart from "duplicated" (only the FIRST end is found, so a
+    // second full copy's body gets stranded in the untouched tail) or "swapped"
+    // (end before start silently duplicates whatever sits between them into the
+    // "replaced" span instead of raising anything). Neither corruption is
+    // something this script can safely repair, so a malformed span is left
+    // completely alone, the same contract uninstall.mjs holds for removal.
+    const span = findMarkerSpan(content, SHELL_MARKER_START, SHELL_MARKER_END);
+    if (!span.ok) {
+      log('skipped', `${shellConfigPath} (${span.reason}, leaving the file untouched)`);
+      return;
+    }
     // Block exists — check if already up to date
-    const existing = content.slice(startIdx, endIdx + SHELL_MARKER_END.length);
+    const existing = content.slice(span.startIdx, span.endIdx + SHELL_MARKER_END.length);
     if (existing === block) {
       log('skipped', `${shellConfigPath} (shell function up to date)`);
       return;
     }
     // Replace stale block
     const updated =
-      content.slice(0, startIdx) + block + content.slice(endIdx + SHELL_MARKER_END.length);
+      content.slice(0, span.startIdx) +
+      block +
+      content.slice(span.endIdx + SHELL_MARKER_END.length);
     if (!dryRun) writeFileSync(shellConfigPath, updated);
     log('merged', `${shellConfigPath} (shell function updated)`);
     return;

package/scripts/lib/design-history-stale.mjs

@@ -69,9 +69,10 @@ function maxDate(dates) {
   return dates.reduce((a, b) => (a > b ? a : b));
 }
 
-// Returns stale findings: { project, lastSession, lastDesignHistory, diffDays }
-// Only includes projects where design-history.md exists AND is stale relative
-// to the latest session-log entry. Date source is body section headings
+// Returns findings: { project, kind, lastSession, lastDesignHistory, diffDays }.
+// `kind` is 'stale' (the file exists but session-log has moved past it) or
+// 'missing' (the file does not exist at all, yet session-log carries at least
+// one design-relevant entry). Date source is body section headings
 // (## YYYY-MM-DD), not frontmatter `updated:` — auto-stage hooks bump the
 // frontmatter on unrelated edits, so it can't signal staleness on its own.
 export function findDesignHistoryStale(hypoDir) {
@@ -81,17 +82,19 @@ export function findDesignHistoryStale(hypoDir) {
   if (!existsSync(projectsDir)) return stale;
 
   for (const name of readdirSync(projectsDir)) {
+    if (name.startsWith('_')) continue; // e.g. templates/projects/_template — not a real project
     const projectDir = join(projectsDir, name);
     if (!statSync(projectDir).isDirectory()) continue;
 
     const dhPath = join(projectDir, 'design-history.md');
-    if (!existsSync(dhPath)) continue;
 
     // session-log can live as a flat `session-log.md` (legacy) or a directory of
     // daily shards `session-log/YYYY-MM-DD.md` (canonical; legacy
     // monthly `YYYY-MM.md` files still appear pre-cutover). This globs every
     // `.md` in the directory, so daily and monthly shapes are both aggregated —
-    // the staleness check needs to see all of them.
+    // the staleness check needs to see all of them. Gathered before the
+    // existsSync(dhPath) branch below, since a project with zero design-history
+    // file still needs this to decide whether it has a design-relevant entry.
     const sessionDates = [];
     const flatSlPath = join(projectDir, 'session-log.md');
     if (existsSync(flatSlPath)) {
@@ -107,16 +110,32 @@ export function findDesignHistoryStale(hypoDir) {
     }
     if (sessionDates.length === 0) continue;
 
+    if (!existsSync(dhPath)) {
+      // The file was never created, so there is nothing to compare dates
+      // against — but parseSessionDates already excluded pure "ADR 없음"
+      // entries, so a non-empty sessionDates here means at least one entry
+      // recorded (or implied) a design change with nowhere to land. This is a
+      // bootstrap gap, not a staleness gap: `lastDesignHistory`/`diffDays` stay
+      // null and callers must key off `kind` to avoid conflating the two.
+      stale.push({
+        project: name,
+        kind: 'missing',
+        lastSession: maxDate(sessionDates).toISOString().slice(0, 10),
+        lastDesignHistory: null,
+        diffDays: null,
+      });
+      continue;
+    }
+
     const dhText = readFileSync(dhPath, 'utf-8');
     const lastSession = maxDate(sessionDates);
     const lastDH = maxDate(parseDates(dhText, DESIGN_HISTORY_DATE_RE));
 
-    if (!lastSession) continue;
-
     if (!lastDH || lastSession > lastDH) {
       const diffDays = lastDH ? Math.round((lastSession - lastDH) / (1000 * 60 * 60 * 24)) : null;
       stale.push({
         project: name,
+        kind: 'stale',
         lastSession: lastSession.toISOString().slice(0, 10),
         lastDesignHistory: lastDH ? lastDH.toISOString().slice(0, 10) : '(없음)',
         diffDays,

package/scripts/lib/extensions.mjs

@@ -29,7 +29,11 @@ import {
   mkdirSync,
   lstatSync,
   statSync,
+  fstatSync,
   chmodSync,
+  fchmodSync,
+  openSync,
+  closeSync,
   rmdirSync,
 } from 'fs';
 import { join, dirname, relative, resolve, posix, sep } from 'path';
@@ -907,14 +911,34 @@ export function withSrcExecBits(destMode, srcMode) {
   return (destMode & ~0o111) | (srcMode & 0o111);
 }
 
+/** Add only the execute bits src has that dest is missing, onto dest — every bit
+ * dest already carries (owner/group/other, ours or the user's) survives untouched.
+ * This is the additive counterpart to `withSrcExecBits` above: that one REPLACES
+ * dest's exec bits wholesale, which is right for a fresh write (there is no prior
+ * dest state worth keeping) but wrong for healing an existing file, where treating
+ * "executable" as one boolean instead of three independent bits made a cross
+ * combination (src owner-only, dest group-only) read as already-satisfied and
+ * never get healed. Used only by copyOne's content-identical branch. */
+export function addSrcExecBits(destMode, srcMode) {
+  return destMode | (srcMode & 0o111);
+}
+
 function writeFreshAtomic(dest, content, srcMode) {
+  // `wx` (O_CREAT|O_EXCL) refuses to open a path that already exists, symlink
+  // included, so a predictable tmp name can't be raced into following one, the
+  // same hardening capture.mjs's own writeAtomic already carries.
   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));
+  const fd = openSync(tmp, 'wx');
+  try {
+    writeFileSync(fd, content);
+    if (srcMode != null) {
+      // No fd-based write has a 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.
+      fchmodSync(fd, withSrcExecBits(fstatSync(fd).mode, srcMode));
+    }
+  } finally {
+    closeSync(fd);
   }
   try {
     renameSync(tmp, dest);
@@ -936,10 +960,17 @@ function writeFreshAtomic(dest, content, srcMode) {
  *
  * 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.
+ * carried onto dest on every branch that (re)writes it. The content-identical
+ * branch below is the exception: it only ADDS a bit src has that dest lacks
+ * (per owner/group/other, not "executable" as one boolean), never turns one
+ * off, since a dest exec bit that src lacks can't be told apart from one the
+ * user set. `typeDir` is the symlink-ancestor boundary for that same branch's
+ * chmod: every caller passes the extension-type root (`~/.claude/hooks`, etc.)
+ * so a symlinked ancestor there is never chmod'd through to whatever it points
+ * at (codex pre-commit BLOCKER — the flat-file and manifest callers had no
+ * such guard, unlike the skill loop's own pre-check on `destPath`).
  */
-function copyOne({ srcPath, destPath, key, recordedSHA, apply, force }) {
+function copyOne({ srcPath, destPath, key, recordedSHA, apply, force, typeDir }) {
   const srcContent = readFileSync(srcPath);
   const srcSHA = sha256(srcContent);
   const srcMode = statSync(srcPath).mode;
@@ -959,17 +990,27 @@ 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.
+    // be a pure no-op, which is exactly why a missing bit here never healed. Only
+    // heal by ADDING the specific bits src has that dest lacks (owner/group/other
+    // checked independently — a prior boolean "is anything executable" check made
+    // a cross combination like src=owner-only/dest=group-only read as already
+    // satisfied and skip healing the owner bit entirely, codex pre-commit BLOCKER).
+    // A dest bit src lacks is always left alone, because that could be this same
+    // heal from an older run, or a bit the user set on purpose, and we have no way
+    // to tell those apart. This also means a wiki copy captured before this fix
+    // (recorded 644 for a 755 local original) can no longer strip the local file
+    // back to 644 on the next sync; it can only ever add bits.
     // 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.
+    // ponytail: add-only means a dest that lost a bit src still has (content
+    // matches, exec bit was stripped some other way) never gets it back either.
+    // 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 healed in both directions.
     const destMode = statSync(destPath).mode;
-    if ((destMode & 0o111) !== (srcMode & 0o111)) {
-      if (apply) chmodSync(destPath, withSrcExecBits(destMode, srcMode));
+    const missingBits = srcMode & 0o111 & ~destMode;
+    if (missingBits !== 0 && !hasSymlinkAncestor(typeDir, destPath)) {
+      if (apply) chmodSync(destPath, addSrcExecBits(destMode, srcMode));
       return { action: 'update', sha: srcSHA };
     }
     return { action: 'up-to-date', sha: srcSHA };
@@ -1097,6 +1138,7 @@ function syncOneSkill({
       recordedSHA: recordedNested[f.rel],
       apply,
       force,
+      typeDir,
     });
     if (res.sha != null) newNested[f.rel] = res.sha;
     result.actions.push({ target, file: fileKey, action: res.action });
@@ -1414,6 +1456,7 @@ export function syncExtensions({
         recordedSHA: recorded[fileKey],
         apply,
         force,
+        typeDir,
       });
       if (fileRes.sha != null) newSHAs[fileKey] = fileRes.sha;
       result.actions.push({ target, file: fileKey, action: fileRes.action });
@@ -1448,6 +1491,7 @@ export function syncExtensions({
           recordedSHA: recorded[mKey],
           apply,
           force,
+          typeDir,
         });
         if (mRes.sha != null) newSHAs[mKey] = mRes.sha;
         result.actions.push({ target, file: mKey, action: mRes.action });

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

@@ -48,6 +48,133 @@ 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';
 
+// ── marker-span validation (shared by both the writer in init.mjs and both
+// removal paths in uninstall.mjs) ───────────────────────────────────────────
+//
+// 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" (or, on the writer's side, the "replaced") span.
+// Neither script 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;
+}
+
+export 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 };
+}
+
+// ── body-shape validation (shared by both removal paths in uninstall.mjs) ──
+//
+// findMarkerSpan proves the span itself is well-formed. It says nothing about
+// what sits INSIDE that span. A well-formed marker pair is trivial to forge
+// around arbitrary content — a user's own shell function, a user's own
+// pre-commit check — and codex reproduced exactly that (2026-08-27): a marker
+// pair wrapped around `echo USER_OWNED_DEPLOY_CHECK` passed every prior check
+// (one start, one end, start before end, a leading shebang) and got deleted
+// along with the user's line, because nothing ever looked at the body text
+// itself. These two functions are that missing check.
+//
+// The shell block is fully static — init never bakes a path into it — so its
+// body can be matched byte-for-byte against SHELL_FUNCTION_BODY below. The
+// pre-commit body cannot: it embeds the absolute install root, which moves
+// across machines and package versions, so requiring an exact match would
+// refuse to remove a hook a real (older, or differently-installed) init.mjs
+// actually wrote. It is matched structurally instead — the "one or two `node
+// '<path>' ... || exit 1` steps, then `exit 0`" shape — checking only that
+// the referenced script is ours (ends in `/hooks/hypo-pre-commit.mjs` or
+// `/scripts/lint.mjs`), not which root it lives under.
+//
+// Both directions of a mismatch here are unequal: failing to recognize a
+// hook init actually wrote costs a re-run with --force-*; deleting a file
+// that was never ours has no recovery. So an unrecognized shape is always
+// treated as "not ours" and left standing, never as "close enough".
+
+const PRE_COMMIT_WORKER_LINE = /^node '(.+)' \|\| exit 1$/;
+const PRE_COMMIT_LINT_LINE = /^node '(.+)' --hypo-dir='(?:.+)' --strict \|\| exit 1$/;
+
+// Reverses shellSingleQuote()'s escaping (a literal `'` becomes `'\''`) so the
+// captured path can be compared against the suffix it must end in.
+function unescapeShellSingleQuoted(s) {
+  return s.split("'\\''").join("'");
+}
+
+/**
+ * @param {string} content full pre-commit hook file content
+ * @param {{startIdx: number, endIdx: number}} span a `findMarkerSpan` result
+ *   already confirmed `ok: true` for WIKI_PRE_COMMIT_MARKER_START/END
+ * @returns {boolean} true when the text between the markers is recognizable
+ *   as a body init.mjs's wikiPreCommitContent() writes
+ */
+export function isOwnedWikiPreCommitBody(content, span) {
+  const body = content.slice(span.startIdx + WIKI_PRE_COMMIT_MARKER_START.length, span.endIdx);
+  const lines = body.split('\n');
+  // wikiPreCommitContent() always places a bare "\n" right after START and
+  // right before END, so the first and last split segments must be empty.
+  if (lines[0] !== '' || lines[lines.length - 1] !== '') return false;
+  const middle = lines.slice(1, -1);
+  if (middle.length < 2 || middle.length > 3 || middle[middle.length - 1] !== 'exit 0') {
+    return false;
+  }
+  const steps = middle.slice(0, -1);
+  const worker = PRE_COMMIT_WORKER_LINE.exec(steps[0]);
+  if (!worker || !unescapeShellSingleQuoted(worker[1]).endsWith('/hooks/hypo-pre-commit.mjs')) {
+    return false;
+  }
+  if (steps.length === 2) {
+    const lint = PRE_COMMIT_LINT_LINE.exec(steps[1]);
+    if (!lint || !unescapeShellSingleQuoted(lint[1]).endsWith('/scripts/lint.mjs')) return false;
+  }
+  return true;
+}
+
+// The exact text init.mjs's shellFunctionBlock() writes between the shell
+// markers. Exported so init.mjs builds the block FROM this constant rather
+// than a second copy of the same literal — the two can then never drift the
+// way independent copies of the pre-commit worker line already could not
+// (see the module-level comment on the markers above).
+export const SHELL_FUNCTION_BODY = `
+function claude() {
+  echo "{\\"cwd\\":\\"$(pwd)\\"}" | node "$HOME/.claude/hooks/hypo-session-start.mjs" > /dev/null 2>&1
+  command claude "$@"
+}
+`;
+
+/**
+ * @param {string} content full rc file content
+ * @param {{startIdx: number, endIdx: number}} span a `findMarkerSpan` result
+ *   already confirmed `ok: true` for SHELL_MARKER_START/END
+ * @returns {boolean} true when the text between the markers is byte-identical
+ *   to what init.mjs writes
+ */
+export function isOwnedShellFunctionBody(content, span) {
+  const body = content.slice(span.startIdx + SHELL_MARKER_START.length, span.endIdx);
+  return body === SHELL_FUNCTION_BODY;
+}
+
 // 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 = [
@@ -82,7 +209,7 @@ function buildScrubbedEnv(localEnvList) {
 // Canonicalize a path that may not exist yet: realpath the deepest existing
 // ancestor and re-append the rest. Without this, a hooks dir git will create
 // lazily could evade the containment check via an unresolved symlinked parent.
-function canonicalize(p) {
+export function canonicalize(p) {
   let cur = resolve(p);
   const tail = [];
   for (;;) {
@@ -101,7 +228,7 @@ function canonicalize(p) {
   }
 }
 
-function isInside(child, parent) {
+export function isInside(child, parent) {
   return child === parent || child.startsWith(parent + sep);
 }