hypomnema 1.7.4 → 1.8.0

package/hooks/hypo-shared.mjs

@@ -1063,6 +1063,63 @@ export function collectProjectWorkingDirs(hypoDir) {
   return out;
 }
 
+// One place that answers "is this string a slug naming a real project directory?".
+// Both resolveGateProjectOverride (a caller-supplied --project) and the gate's
+// mustEvaluate filter (slugs arriving from a transcript or a marker) need it, and
+// having the grammar in two inline copies is the duplication this release spent a
+// codex round removing elsewhere. Not exported: scripts/ has its own validator,
+// and importing that here would invert the one-way hooks/ <- scripts/ dependency.
+function isProjectSlugDirectory(hypoDir, slug) {
+  if (typeof slug !== 'string' || !/^[A-Za-z0-9._-]+$/.test(slug)) return false;
+  if (/^\.+$/.test(slug) || !/[A-Za-z0-9]/.test(slug)) return false;
+  try {
+    return statSync(join(hypoDir, 'projects', slug)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// session-close-scope-boundary spec §2: the one place that turns a caller-
+// supplied project name into precompactGateStatus's opts.projectOverride. Four
+// call sites share it (--mark-session-closed, apply's auto-marker, PreCompact,
+// Stop) so a foreign project's dangling close files demote to a notice instead
+// of blocking a session that never touched them, everywhere the gate runs.
+//
+// `project` is trusted nowhere upstream of this function: crystallize.mjs's
+// own --project only gets slug-syntax + directory-existence checked when the
+// CLI itself parses it (parseArgs + requireProjectDir); a value that arrives
+// via a hook payload or apply's JSON body never passes through that. So this
+// re-validates from scratch — same charset rule as project-create.mjs's
+// isValidProjectName, duplicated rather than imported because hooks/ cannot
+// import scripts/ (dependency direction is one-way) — plus a directory
+// existence check. Either failure returns null, the same as "no project was
+// given": a garbage slug must never narrow the gate's scope, only a real one
+// may (spec success criterion: "opts.projectOverride 가 없는 slug 이면 게이트가
+// 그것을 거절한다").
+//
+// With no `project`, the override is inferred from `sessionCwd` via
+// pickProjectByCwd's rejectAmbiguous mode — the same mode the gate's own
+// close-cwd check already trusts. Without rejectAmbiguous, two projects
+// sharing one working_dir (a monorepo with no uniqueness invariant) would
+// silently resolve to the first slug and could narrow the gate to a project
+// whose OWN close is still incomplete while the real cwd project goes
+// unchecked. A decline here (null) is not a failure: precompactGateStatus
+// falls back to the global, unscoped judgment, which is exactly the STOP-hook
+// call site's actual point (session-close-scope-boundary spec §2: "해석 실패면
+// 기존 fail-closed 가 받아 준다는 틀렸다 ... cwd 미해결을 마커 차단으로 만들지 않는다").
+//
+// @param {string} hypoDir
+// @param {{project?: string|null, sessionCwd?: string|null}} [opts]
+// @returns {string|null}
+export function resolveGateProjectOverride(hypoDir, { project = null, sessionCwd = null } = {}) {
+  if (project) {
+    return isProjectSlugDirectory(hypoDir, project) ? project : null;
+  }
+  return pickProjectByCwd(collectProjectWorkingDirs(hypoDir), sessionCwd, {
+    rejectAmbiguous: true,
+  });
+}
+
 // A project without a working_dir anchor (no index.md, or an index.md missing
 // the field) never enters collectProjectWorkingDirs' universe, so cwd-first
 // resume always MISSes for it — the SessionStart/CwdChanged MISS branch would
@@ -1451,7 +1508,7 @@ function closeCandidateSlugs(hypoDir, dates) {
         // slug yields a token that no longer maps to a `projects/<slug>/`
         // directory — gating on disk keeps it out of the dangling-close set.
         // Directory (not bare-exists) mirrors the apply-path project check
-        // (crystallize.mjs:193).
+        // (crystallize-args.mjs).
         const dir = join(projectsDir, m[1]);
         if (existsSync(dir) && statSync(dir).isDirectory()) slugs.add(m[1]);
       }
@@ -1526,10 +1583,17 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
   // projectOverride (check-only): the caller (`crystallize --check-session-close
   // --project=<slug>`) wants THIS project's close status, not the recency pick —
   // bypass discovery and report the single project, preserving the global return
-  // shape. NEVER threaded from a marker-writing path (--mark / apply auto-marker /
-  // PreCompact): those stay global so the marker == compact-ready invariant holds
-  // (codex design review). A green status here is a project-scoped
-  // diagnostic, not the global compact-readiness verdict.
+  // shape. This is the ONLY caller of projectOverride now: the four marker-writing
+  // paths (--mark / apply auto-marker / PreCompact / Stop) attribute through
+  // `opts.attributionScope` instead (resolveCloseScope, below this function), which
+  // only widens the mine/foreign partition's scope Set and leaves this function
+  // evaluating every project, same as an unscoped call. A green status here is a
+  // project-scoped diagnostic, not the global compact-readiness verdict. The
+  // invariant that once justified keeping the writer paths fully unscoped
+  // ("marker == compact-ready", codex design review) is superseded by that
+  // partition, not restored by it — a marker's own `verified_scope`, attesting
+  // exactly what it checked, is still missing (session-close-scope-boundary
+  // spec §3, next wave).
   if (opts.projectOverride) {
     const s = sessionCloseFileStatus(hypoDir, { projectOverride: opts.projectOverride });
     return {
@@ -1547,11 +1611,30 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
   }
   const dates = freshDates();
   const recency = resolveActiveProject(hypoDir); // no cwd — close never picks by cwd
-  const todayActive = [...closeCandidateSlugs(hypoDir, dates)].filter((p) =>
+  // opts.mustEvaluate: slugs this session ATTRIBUTED its close to (explicit
+  // --project, transcript close-file edits, a prior marker). They are evaluated
+  // even when they are not today-active candidates, because the marker writer
+  // stamps the attribution scope: a slug that reaches the marker but never
+  // reached this evaluation would be attested as closed without ever being
+  // checked (codex pre-commit BLOCKER, reproduced with an empty projects/orphan/).
+  // `projects/<slug>/` must exist on disk; a slug naming a directory that is gone
+  // (a stale marker inside its 7-day TTL) is dropped rather than turned into a
+  // permanent blocker for a project nobody can close any more.
+  // existsSync alone would admit a file, or a traversal like '..', from a
+  // malformed marker or transcript slug and turn it into a surprise blocker.
+  // Same slug grammar the CLI and resolveGateProjectOverride validate against.
+  const mustEvaluate = [...(opts.mustEvaluate || [])].filter((p) =>
+    isProjectSlugDirectory(hypoDir, p),
+  );
+  // The fallback decision reads REAL today activity only. Letting mustEvaluate
+  // populate it would mean an attributed slug suppresses the "this session closed
+  // nothing at all" branch, and that branch is a fail-closed guard the partition
+  // below depends on (`!close.fallback`).
+  const activeCandidates = [...closeCandidateSlugs(hypoDir, dates)].filter((p) =>
     hasTodayCloseActivity(hypoDir, p, dates),
   );
 
-  if (todayActive.length === 0) {
+  if (activeCandidates.length === 0) {
     const legacy = sessionCloseFileStatus(hypoDir);
     return {
       ok: legacy.ok,
@@ -1567,6 +1650,8 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
     };
   }
 
+  const todayActive = [...new Set([...activeCandidates, ...mustEvaluate])];
+
   // primary = the recency project when it is itself today-active, else the first
   // today-active slug (stable order from the candidate set). Used only as the
   // single-slug alias for the message header and the flat `close.project` field.
@@ -3504,6 +3589,12 @@ export function partitionLintScope(findings, scope) {
  * every close. Same path policy as the lint-scope matcher above: separators
  * normalized to POSIX, exact prefix at a segment boundary.
  */
+// This function keeps the posixPath() normalization deliberately, unlike
+// isForeign (§2b), which reads the raw porcelain path so a literal-backslash
+// filename cannot be misread as a nested projects/<slug>/ path. Every caller
+// of isUnderProjectDirs would need to be checked before applying the same
+// raw-path treatment here, and that audit has not been done, so the existing
+// behavior stays until it has.
 export function isUnderProjectDirs(file, slugs) {
   const f = posixPath(file);
   return (slugs || []).some((s) => s && (f === `projects/${s}` || f.startsWith(`projects/${s}/`)));
@@ -3550,6 +3641,15 @@ function projectsFromTouchedCloseFiles(transcriptPath, hypoDir) {
  *      the `project` that same writer recorded, so the two can never disagree.
  */
 export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
+  // `direct` is the subset attributable to THIS close attempt: explicit
+  // --project/closeScope, this session's transcript close-file edits, and the
+  // resolved attributionScope. A marker's `projects` is PAST evidence of a close
+  // that already happened, so it belongs in the partition scope (it must not be
+  // demoted as foreign debt) but NOT in the mandatory-evaluation set: a 7-day-TTL
+  // marker naming a project that is no longer today-active would otherwise make
+  // that project's stale close block an unrelated close today (codex round 2,
+  // reproduced with a 24h-old marker). The returned Set carries `direct` as a
+  // property so the caller does not re-derive it, and the transcript is parsed once.
   const scope = new Set(opts.closeScope || []);
   for (const p of projectsFromTouchedCloseFiles(opts.transcriptPath, hypoDir)) scope.add(p);
   // Marker attribution (session-close attribution). A v4 marker carries `projects` — the
@@ -3561,6 +3661,20 @@ export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
   // above (explicit close scope or transcript close-file edits) already corroborate
   // the SAME slug; otherwise it stays a display hint. This narrow gap self-heals as
   // pre-v4 markers expire (7-day TTL).
+  // opts.attributionScope (session-close-scope-boundary spec §2/§3): a fourth
+  // signal, one slug, from resolveGateProjectOverride. A cwd that unambiguously
+  // owns one project, or an explicit --project the caller already validated, is
+  // evidence this session is closing THAT project — the same standing the three
+  // signals above already have. It is the opt key the four marker-writing paths
+  // (PreCompact, Stop, --mark-session-closed, apply's auto-marker) pass instead
+  // of `opts.projectOverride`: that key stays the check-only diagnostic's (it
+  // also narrows sessionCloseGlobalStatus's own evaluation and turns off the
+  // partition below), while this one only widens the set the partition demotes
+  // everything outside of.
+  if (opts.attributionScope) scope.add(opts.attributionScope);
+  // Snapshot the direct signals BEFORE the marker union below widens the set.
+  scope.direct = new Set(scope);
+
   if (Array.isArray(marker?.projects)) {
     for (const p of marker.projects) if (p) scope.add(p);
   }
@@ -3590,12 +3704,22 @@ export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
  * opts.projectOverride (CHECK-ONLY) narrows BOTH the close status and the lint
  * scope to a single project, for `--check-session-close --project=<slug>`. A
  * green result is then a project-scoped diagnostic, NOT the global compact-ready
- * verdict: the caller must surface the scope. It is NEVER passed from
- * a marker-writing path (--mark / apply auto-marker / PreCompact); those stay
- * global so a marker can't attest compact-ready while PreCompact re-checks red
- * (the marker == compact-ready invariant, codex design review). When a
- * log-only marker governs the session, log-only mode wins and projectOverride is
- * ignored.
+ * verdict: the caller must surface the scope. The four marker-writing paths
+ * (--mark / apply auto-marker / PreCompact / Stop) never set this — they pass
+ * `opts.attributionScope` instead, which only feeds resolveCloseScope's set and
+ * leaves this status evaluating every project, so the mine/foreign partition
+ * below can tell their own incomplete close from someone else's debt. The
+ * invariant that once justified keeping those paths fully unscoped ("marker ==
+ * compact-ready", codex design review) is replaced by that partition, not
+ * restored by it — a marker's own `verified_scope`, attesting exactly what it
+ * checked, is still missing (session-close-scope-boundary spec §3, next wave).
+ * Either key ALSO feeds the git-dirty partition (spec §2b): with an untrusted
+ * transcript (missing/corrupt), a dirty file structurally under a DIFFERENT
+ * eligible project's own directory is demoted to a notice, because the path
+ * alone proves it is not this session's; everything else keeps blocking.
+ * When a log-only marker governs the session, log-only mode wins for the
+ * close-status and lint scope (scope selection above); the git-dirty
+ * partition in spec §2b still applies regardless of projectOverride.
  *
  * @param {string} hypoDir
  * opts.sessionCwd (session-cwd close check): the authoritative cwd of the session being
@@ -3606,7 +3730,7 @@ export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
  * cwd yields a best-effort notice, not a block. apply never passes it (its launch
  * cwd may differ from the authoritative payload.project).
  *
- * @param {{lintScope?: Iterable<string>, transcriptPath?: string|null, claudeHome?: string, projectOverride?: string|null, sessionCwd?: string|null, sessionId?: string|null, logOnly?: boolean, closeScope?: string[]}} [opts]
+ * @param {{lintScope?: Iterable<string>, transcriptPath?: string|null, claudeHome?: string, projectOverride?: string|null, attributionScope?: string|null, sessionCwd?: string|null, sessionId?: string|null, logOnly?: boolean, closeScope?: string[]}} [opts]
  * @returns {{ok: boolean, close: object, blockers: {type:string,reason:string}[], notices: {type:string,reason:string,file?:string}[], driftTargets: string[], skipped: {lint:boolean, feedback:boolean}}}
  */
 export function precompactGateStatus(hypoDir, opts = {}) {
@@ -3656,10 +3780,25 @@ export function precompactGateStatus(hypoDir, opts = {}) {
   // would make almost every real transcript untrusted and defeat the scoping
   // this fix exists to add.
   let sessionTouchTrusted = false;
+  // Transcript-derived files ONLY (not closeAccountableScope's mandatory-files
+  // base, which comes from closeFileTargetsGlobal and would fold every close
+  // file of every eligible project into "this session touched it"). §2b's
+  // isForeign below needs exactly this narrower set: a file this session's own
+  // Edit/Write proves it touched, even on a PARTIALLY-parsed transcript (the
+  // trailing line of an append-in-progress JSONL truncates in the ordinary
+  // course of a live session, not as an exceptional failure), must never be
+  // classified foreign by path prefix alone. Widening this to
+  // closeAccountableScope would re-open the exact foreign-close-file leak
+  // (b) fixed above (a genuinely different project's close file would count
+  // as "touched" just because it shares the mandatory-files base).
+  let transcriptTouched = new Set();
   if (opts.transcriptPath) {
     const widened = extractTouchedWikiFilesWithTrust(opts.transcriptPath, hypoDir);
     sessionTouchTrusted = widened.trusted;
-    for (const f of widened.files) closeAccountableScope.add(f);
+    for (const f of widened.files) {
+      closeAccountableScope.add(f);
+      transcriptTouched.add(f);
+    }
   }
 
   // 1. wiki git state. Uncommitted changes (real unsaved work) BLOCK, but only
@@ -3686,7 +3825,72 @@ export function precompactGateStatus(hypoDir, opts = {}) {
   const git = hypoIsClean(hypoDir);
   if (git.uncommitted) {
     const dirty = gitDirtyFiles(hypoDir);
-    if (dirty.length === 0 || !sessionTouchTrusted) {
+    if (dirty.length === 0) {
+      // Enumeration itself failed (or nothing is actually dirty despite the
+      // porcelain status): "cannot attribute" is not "clean", block exactly
+      // as before, override or not.
+      blockers.push({ type: 'git', reason: git.reason });
+    } else if (!sessionTouchTrusted && (opts.projectOverride || opts.attributionScope)) {
+      // session-close-scope-boundary spec §2b: a broken/missing transcript
+      // normally means "cannot attribute, fail closed" (the branch below).
+      // But when the CALLER told us which project is ours (an explicit
+      // --project, or the cwd-derived attributionScope), a dirty file that
+      // lives structurally under a DIFFERENT eligible project's own directory
+      // needs no attribution inference at all: the path alone proves it is
+      // not this session's file. Everything else (this session's own
+      // project, pages/, an unregistered or _template project dir) keeps the
+      // pre-existing fail-closed behavior; only a provably-foreign path is
+      // demoted.
+      const effectiveOverride = opts.projectOverride || opts.attributionScope;
+      // Computed once per gate call, never per file (collectProjectWorkingDirs
+      // walks the projects/ dir and reads every index.md). A throw here (a
+      // readdirSync failure it does not catch itself) must not escape as an
+      // exception, the PreCompact hook's outermost catch would turn that
+      // into a silent, fully-suppressed gate result, the opposite of "fail
+      // closed". Treat any failure as "no eligible projects known", which
+      // makes isForeign() below always false and every dirty file falls
+      // through to the unconditional blocker.
+      let eligibleSlugs = null;
+      try {
+        eligibleSlugs = new Set(collectProjectWorkingDirs(hypoDir).map((p) => p.slug));
+      } catch {
+        eligibleSlugs = null;
+      }
+      // Lexical, on the RAW git-porcelain path, BEFORE posixPath()'s
+      // unconditional `\` -> `/` conversion. A file whose actual NAME
+      // contains a literal backslash (`projects\other\x.md`, one path
+      // segment, no real subdirectory) must not be reinterpreted as living
+      // under `projects/other/` just because posixPath() would rewrite it
+      // that way; testing the raw string here means it never matches this
+      // regex and falls through to fail-closed instead.
+      const isForeign = (f) => {
+        // The transcript already PROVES this session edited f, whatever its
+        // path prefix says: transcript evidence outranks the path-prefix
+        // heuristic below, which only exists to cover files the (untrusted)
+        // transcript could not vouch for either way.
+        if (transcriptTouched.has(posixPath(f))) return false;
+        if (!eligibleSlugs) return false;
+        const m = /^projects\/([^/]+)\/.+$/.exec(f);
+        if (!m) return false;
+        const slug = m[1];
+        return slug !== effectiveOverride && eligibleSlugs.has(slug);
+      };
+      const foreign = dirty.filter(isForeign);
+      const rest = dirty.filter((f) => !isForeign(f));
+      if (rest.length > 0) {
+        blockers.push({
+          type: 'git',
+          reason: `uncommitted changes in ${hypoDir}: ${rest.join(', ')}`,
+        });
+      }
+      for (const f of foreign) {
+        notices.push({
+          type: 'git',
+          file: f,
+          reason: `uncommitted changes outside this session's scope: ${f}`,
+        });
+      }
+    } else if (!sessionTouchTrusted) {
       blockers.push({ type: 'git', reason: git.reason });
     } else {
       const mine = dirty.filter((f) => closeAccountableScope.has(posixPath(f)));
@@ -3739,8 +3943,21 @@ export function precompactGateStatus(hypoDir, opts = {}) {
     }
   } else {
     // projectOverride narrows the close status to one project (check-only); a
-    // marker-writing caller never sets it, so the marker path stays global.
-    close = sessionCloseGlobalStatus(hypoDir, { projectOverride: opts.projectOverride });
+    // marker-writing caller never sets it. It attributes instead through
+    // opts.attributionScope, consumed a few lines down by resolveCloseScope, so
+    // the status computed here stays global and only the partition below scopes it.
+    // scopeSet is computed BEFORE the status so the attributed slugs become
+    // mandatory evaluation targets (sessionCloseGlobalStatus's mustEvaluate).
+    // Computing it after would let a slug reach the marker that the status never
+    // looked at, which is the false-green this ordering exists to stop.
+    const attributedScope = resolveCloseScope(hypoDir, opts, marker);
+    close = sessionCloseGlobalStatus(hypoDir, {
+      projectOverride: opts.projectOverride,
+      // direct only: a past marker's projects must not become mandatory
+      // evaluation targets (codex round 2). They stay in attributedScope so the
+      // partition still treats them as this session's, not foreign debt.
+      mustEvaluate: attributedScope.direct,
+    });
 
     // Attribute the close debt before blocking on it. An incomplete close belongs
     // to whichever session performed it; charging it to an unrelated session is the
@@ -3771,7 +3988,7 @@ export function precompactGateStatus(hypoDir, opts = {}) {
     // pre-existing tradeoff documented there). And the marker is never written, so the
     // Stop hook still refuses to end the session. Closing this properly needs a
     // durable close-attempt record; it is not worth a new state-file lifecycle here.
-    const scopeSet = resolveCloseScope(hypoDir, opts, marker);
+    const scopeSet = attributedScope;
     const failed = (close.projects || []).filter((p) => !p.ok);
     const partition =
       !close.fallback && !opts.projectOverride && scopeSet.size > 0 && failed.length > 0;
@@ -3878,6 +4095,11 @@ export function precompactGateStatus(hypoDir, opts = {}) {
       // monorepo tie pickProjectByCwd declined): we cannot attribute a close
       // responsibility, so we do NOT hard-block (nothing proves there is anything
       // to close). Surface a best-effort notice so the coverage gap is visible.
+      // This reason names --project / --log-only, the crystallize CLI flags:
+      // correct for a --check-session-close caller, but not a lever a
+      // PreCompact hook reader has. The hook renderer (hypo-personal-check.mjs)
+      // builds its own sentence for this notice type instead of echoing this
+      // one verbatim; keep both in sync if the underlying condition changes.
       notices.push({
         type: 'close-cwd-unresolved',
         reason:

package/hooks/version-check.mjs

@@ -156,16 +156,54 @@ export function selectPluginVersion(plugins) {
   return typeof v === 'string' ? v : null;
 }
 
-/** Channel-specific one-line update instruction. */
+/** The command that runs an upgrade apply, in the form the caller's channel can
+ *  actually run. A plugin-only install has no `hypomnema` on PATH: that binary is
+ *  the npm package's bin, while the plugin manifest ships commands only. And the
+ *  slash command takes no `--apply` argument, so naming the flag there describes
+ *  a call it does not make: it runs the check and appends --apply only after the
+ *  operator confirms.
+ *
+ *  Lives here because both hooks and scripts need it and the dependency only
+ *  runs one way (scripts import hooks, never the reverse). This file is already
+ *  in hooks.json's `shared` list, so it reaches every standalone install.
+ *
+ *  Use UPGRADE_APPLY_EITHER when the target channel is genuinely unknown, e.g.
+ *  an instruction about a DIFFERENT machine. */
+export function upgradeApplyHint(isPluginChannel) {
+  return isPluginChannel
+    ? '`/hypo:upgrade` (confirm the apply step)'
+    : '`hypomnema upgrade --apply`';
+}
+
+export const UPGRADE_APPLY_EITHER =
+  '`hypomnema upgrade --apply` (or `/hypo:upgrade` on a plugin install)';
+
+/** Channel-specific one-line update instruction.
+ *
+ *  Every channel ends with the same second step. Installing a release does NOT
+ *  repoint the vault's git pre-commit hook: that hook holds an absolute path
+ *  baked in at init time, and only `upgrade --apply` rewrites it. No hook can
+ *  do it either (a hook must never invoke an apply path). Without this line the
+ *  user updates, sees the new version string, and keeps committing through the
+ *  install they had when they first ran init. */
 export function buildUpdateLine(channel, current, latest) {
   const head = `[Hypomnema] Update available! ${current} → ${latest}`;
+  // The repoint step has to be RUNNABLE on the channel it is printed for. A
+  // plugin-only install has no `hypomnema` on PATH (that binary is the npm
+  // package's bin; the plugin manifest ships commands only), so its form is the
+  // slash command. And the slash command takes no --apply argument: that
+  // command runs the check first and only appends --apply after the operator
+  // confirms, so naming the flag there would describe a call the command does
+  // not make. Both mistakes are the same class as naming a flag no script parses.
+  const repoint = (cmd) => `\n  → then: ${cmd}  (repoints the vault's git hook at the new install)`;
   if (channel === 'plugin') {
-    return `${head}\n  → run: /plugin marketplace update hypomnema  then  /reload-plugins`;
-  }
-  if (channel === 'npm') {
-    return `${head}\n  → run: npm install -g hypomnema`;
+    return `${head}\n  → run: /plugin marketplace update hypomnema  then  /reload-plugins${repoint(upgradeApplyHint(true))}`;
   }
-  return `${head}\n  → npm i -g hypomnema  (or  /plugin marketplace update hypomnema && /reload-plugins)`;
+  // The only remaining displayed channel is npm: computeNotice drops 'unknown'
+  // before anything renders, and a dual install reports the channel of the hook
+  // root actually running, never a third "mixed" value. A branch for one would
+  // be code no user reaches.
+  return `${head}\n  → run: npm install -g hypomnema${repoint(upgradeApplyHint(false))}`;
 }
 
 // ── cache freshness + notice decision (pure) ─────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,11 @@
     "scripts/verify.mjs",
     "scripts/weekly-report.mjs",
     "scripts/lib/core-hooks.mjs",
+    "scripts/lib/crystallize-args.mjs",
+    "scripts/lib/crystallize-close-apply.mjs",
+    "scripts/lib/crystallize-close-check.mjs",
+    "scripts/lib/crystallize-close-gate.mjs",
+    "scripts/lib/crystallize-helpers.mjs",
     "scripts/lib/design-history-stale.mjs",
     "scripts/lib/extensions.mjs",
     "scripts/lib/failure-type.mjs",
@@ -53,7 +58,8 @@
     "templates/",
     "docs/",
     ".claude-plugin/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "wiki",
@@ -92,6 +98,6 @@
     "prepublishOnly": "npm test && npm run lint && npm run check:versions && npm run smoke:plugin && node scripts/check-pack-surface.mjs && npm run smoke-pack && npm run check:bilingual && npm run check:tracker-ids"
   },
   "devDependencies": {
-    "prettier": "^3.8.3"
+    "prettier": "3.8.3"
   }
 }

package/scripts/capture.mjs

@@ -32,6 +32,7 @@
  * acquired through the normal sync path, never by injecting a SHA directly.
  */
 
+import { UPGRADE_APPLY_EITHER } from '../hooks/version-check.mjs';
 import {
   existsSync,
   readFileSync,
@@ -76,6 +77,8 @@ import {
   scanSettingsHooks,
   parseCapturableHookCommand,
   HOOK_EVENT_ALLOWLIST,
+  HOOK_INTERPRETER_EXT,
+  DEFAULT_HOOK_INTERPRETER,
   SKILL_ROOT_FILE,
   EXT_PREFIX,
   withSrcExecBits,
@@ -90,8 +93,9 @@ const HOME = homedir();
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 // Captured types and their singular manifest `type` value. commands/agents install
-// as top-level `.md` files; hooks install as `.mjs` and additionally register a
-// settings.json entry (reverse of forward-sync); skills install as a DIRECTORY.
+// as top-level `.md` files; hooks install as an interpreter-specific executable
+// (.mjs/.py/.sh) and additionally register a settings.json entry
+// (reverse of forward-sync); skills install as a DIRECTORY.
 const CAPTURE_TYPES = ['commands', 'agents', 'hooks', 'skills'];
 // The flat, single-file types. `TYPE_EXT` has no `skills` entry on purpose: a skill
 // has no install extension, and letting it through a flat helper would silently
@@ -101,7 +105,20 @@ const FLAT_TYPES = ['commands', 'agents', 'hooks'];
 // registration instead, and skills have their own directory scanner.
 const READDIR_TYPES = ['commands', 'agents'];
 const TYPE_SINGULAR = { commands: 'command', agents: 'agent', hooks: 'hook', skills: 'skill' };
-const TYPE_EXT = { commands: '.md', agents: '.md', hooks: '.mjs' };
+// `TYPE_EXT` has no `hooks` entry either, for the same reason as skills: a hook's
+// extension depends on its interpreter (HOOK_INTERPRETER_EXT), not its type.
+// captureFileExt() is the one place that resolves it; every hook-touching call
+// site below goes through that, not this map.
+const TYPE_EXT = { commands: '.md', agents: '.md' };
+
+/** The install/wiki-storage extension for one capture candidate. hooks vary by
+ * interpreter (mirrors buildHookCommand/parseCapturableHookCommand in
+ * extensions.mjs); the other flat types have one fixed extension. */
+function captureFileExt(c) {
+  return c.type === 'hooks'
+    ? HOOK_INTERPRETER_EXT[c.interpreter ?? DEFAULT_HOOK_INTERPRETER]
+    : TYPE_EXT[c.type];
+}
 
 // Ceilings for a captured skill subtree (skills-capture design §3). A hand-authored
 // skill is a handful of files; a vendored one (gstack: 14,311 files / 1.1GB, mostly
@@ -124,9 +141,14 @@ function pkgJsonPath() {
  * hooks/commands + already-synced hypo-ext-* copies), anything already owned
  * (a recorded SHA for its install path means the wiki already manages it), and
  * non-.md files. Symlink/non-regular is checked by the caller (needs an fs stat).
+ * `type` must be a flat readdir type with a single fixed extension (TYPE_EXT);
+ * hooks have no entry there (extension depends on interpreter) and are never
+ * routed through this function — scanCandidates only calls it for READDIR_TYPES.
  */
 export function isCaptureCandidate(type, file, recorded) {
-  if (!file.endsWith(TYPE_EXT[type])) return { ok: false, reason: `not a ${TYPE_EXT[type]} file` };
+  const ext = TYPE_EXT[type];
+  if (!ext) return { ok: false, reason: `capture-by-readdir does not cover ${type}` };
+  if (!file.endsWith(ext)) return { ok: false, reason: `not a ${ext} file` };
   const lower = file.toLowerCase();
   if (lower === 'hypo' || lower.startsWith('hypo-')) {
     return { ok: false, reason: 'reserved hypo namespace' };
@@ -296,10 +318,14 @@ export function planSkillCapture({
 /**
  * Reverse-generate the sidecar manifest for a capture candidate. commands/agents
  * carry only `{ type, installName }`; hooks additionally carry the settings
- * registration fields `{ event, matcher?, timeout? }`. matcher/timeout are omitted
- * when absent (an empty-string matcher is already normalized to undefined by the
- * scanner) via conditional spread, so the in-memory object never carries an
- * `undefined`-valued key that would break the planCapture deep-equality check.
+ * registration fields `{ event, matcher?, timeout?, interpreter? }`. Every
+ * optional field is omitted when it would equal its default (an empty-string
+ * matcher is already normalized to undefined by the scanner; `node` is the
+ * default interpreter) via conditional spread, so the in-memory object never
+ * carries an `undefined`-valued key or a redundant explicit default, either of
+ * which would break the planCapture deep-equality check against a manifest
+ * captured before interpreter support landed (a `.mjs` hook's manifest must stay byte-for-byte
+ * identical, or every prior capture becomes a false conflict).
  */
 function buildWantManifest(c) {
   const manifest = { type: TYPE_SINGULAR[c.type], installName: c.stem };
@@ -307,6 +333,9 @@ function buildWantManifest(c) {
     manifest.event = c.event;
     if (c.matcher !== undefined && c.matcher !== '') manifest.matcher = c.matcher;
     if (c.timeout !== undefined) manifest.timeout = c.timeout;
+    if (c.interpreter !== undefined && c.interpreter !== DEFAULT_HOOK_INTERPRETER) {
+      manifest.interpreter = c.interpreter;
+    }
   }
   return manifest;
 }
@@ -438,8 +467,9 @@ function subsetOf(keys, allowed) {
  * canonical.
  *
  * A candidate must satisfy ALL of: strict command grammar
- * (`parseCapturableHookCommand`) resolving under `~/.claude/hooks/`; the resolved
- * `.mjs` is a real regular file (no symlink / non-regular); `type === 'command'`;
+ * (`parseCapturableHookCommand`, which also recovers the interpreter — node,
+ * python3, or bash) resolving under `~/.claude/hooks/`; the resolved
+ * file is a real regular file (no symlink / non-regular); `type === 'command'`;
  * the event is in `HOOK_EVENT_ALLOWLIST`; a preservable shape (F3); the case-folded
  * basename appears exactly once across all settings hooks (F6); and the stem is not
  * a core hook, not the reserved hypo namespace, and not already wiki-owned.
@@ -479,7 +509,7 @@ export function scanHookCandidates(claudeHome, settingsPath, recorded, coreBasen
       skipped.push({ type: 'hooks', command: rec.command, reason: parsed.reason });
       continue;
     }
-    const { stem, basename } = parsed;
+    const { stem, basename, interpreter } = parsed;
     const label = `hooks/${basename}`;
 
     // Duplicate first: a basename registered 2+ times is uniformly skipped so both
@@ -547,6 +577,7 @@ export function scanHookCandidates(claudeHome, settingsPath, recorded, coreBasen
       event: rec.event,
       matcher: rec.matcher,
       timeout: rec.timeout,
+      interpreter,
       label,
     });
   }
@@ -993,7 +1024,7 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
       captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped, created });
       continue;
     }
-    const fileExt = TYPE_EXT[c.type];
+    const fileExt = captureFileExt(c);
     const wikiStem = `${EXT_PREFIX}${c.stem}`;
     const typeDir = join(extDir, c.type);
     const filePath = join(typeDir, `${wikiStem}${fileExt}`);
@@ -1024,11 +1055,12 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
     const plan = planCapture({ wantManifest, srcSha, existingFileSha, existingManifestRaw });
 
     // installFile is the ORIGINAL name the far machine installs under (installName
-    // adoption); for hooks that is `<stem>.mjs`, for commands/agents `<stem>.md`.
+    // adoption); for hooks that is `<stem>` plus its interpreter's extension
+    // (`.mjs`/`.py`/`.sh`), for commands/agents `<stem>.md`.
     const installFile = `${c.stem}${fileExt}`;
     // Ownership keys sync must record for the adoption to count. Hooks track BOTH
-    // the `.mjs` and its `.manifest.json` sidecar under the install path (success
-    // criterion d); commands/agents track only the single install file.
+    // the main file and its `.manifest.json` sidecar under the install path
+    // (success criterion d); commands/agents track only the single install file.
     const requiredKeys =
       c.type === 'hooks'
         ? [`hooks/${installFile}`, `hooks/${c.stem}.manifest.json`]
@@ -1173,7 +1205,7 @@ function report(captured, skipped, failed, dryRun) {
       const dest =
         c.type === 'skills'
           ? `extensions/skills/${EXT_PREFIX}${c.stem}/`
-          : `extensions/${c.type}/${EXT_PREFIX}${c.stem}${TYPE_EXT[c.type]}`;
+          : `extensions/${c.type}/${EXT_PREFIX}${c.stem}${captureFileExt(c)}`;
       log(`  ${c.type}/${c.file} → ${dest}`);
     }
   }
@@ -1182,7 +1214,7 @@ function report(captured, skipped, failed, dryRun) {
     log(`Failed to adopt ${failed.length} (see sync warnings; wiki files rolled back).`);
   if (!dryRun && captured.some((c) => c.status === 'captured')) {
     log('');
-    log('Next: commit + push the wiki, then run `hypomnema upgrade --apply` on another machine.');
+    log(`Next: commit + push the wiki, then run ${UPGRADE_APPLY_EITHER} on another machine.`);
   }
 }