hypomnema 1.2.1 → 1.3.1

package/hooks/hypo-session-start.mjs

@@ -37,6 +37,10 @@ import {
   computeNotice,
   markNotified,
   isOptedOut,
+  resolveCliOnPath,
+  computeSiblingNotice,
+  siblingAlreadyNotified,
+  markSiblingNotified,
 } from './version-check.mjs';
 
 // Privacy guard: refuse to read+inject .hypoignore-matched
@@ -119,6 +123,45 @@ function buildUpdateNotice() {
   }
 }
 
+/**
+ * Stale-sibling notice (ADR 0038, D3). The update-notifier above only knows
+ * whether the ACTIVE install is behind latest — it is blind to an OLDER sibling
+ * that owns the `hypomnema` bin on PATH. That sibling is the live footgun:
+ * running `hypomnema init`/`upgrade` through it downgrades the active hooks.
+ *
+ * This is the ONLY surface that reaches a user already in that state, because it
+ * runs from the (newer) active hook — `doctor` invoked via the stale CLI would
+ * run the stale doctor. fs-only (no npm/which spawn). Throttled via the cache so
+ * it nags once per (cliPath@cliVersion → activeVersion) tuple. Best-effort.
+ */
+function buildSiblingNotice() {
+  try {
+    if (isOptedOut()) return '';
+    // Active install identity = hypo-pkg.json (what init/upgrade write). This is
+    // the authoritative pkgRoot+version; ACTIVE_ROOT (~/.claude) has no package.json.
+    let active = null;
+    try {
+      active = JSON.parse(readFileSync(join(homedir(), '.claude', 'hypo-pkg.json'), 'utf-8'));
+    } catch {
+      return ''; // no active metadata → nothing to compare a sibling against
+    }
+    if (!active || !active.pkgVersion) return '';
+    const cli = resolveCliOnPath('hypomnema');
+    const notice = computeSiblingNotice(cli, {
+      pkgRoot: active.pkgRoot,
+      version: active.pkgVersion,
+    });
+    if (!notice) return '';
+    const cachePath = defaultCachePath();
+    const cache = readCache(cachePath);
+    if (siblingAlreadyNotified(cache, notice.key)) return '';
+    markSiblingNotified(cachePath, notice.key);
+    return notice.line;
+  } catch {
+    return '';
+  }
+}
+
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
 const GROWTH_CACHE = join(HYPO_DIR, '.cache', 'last-session-growth.json');
 
@@ -170,7 +213,7 @@ function gitPull(dir) {
 
 /**
  * fix #10: surface unresolved sync failures recorded by a prior session's
- * Stop hook (#9). The entry is cleared only once this session's pull has
+ * Stop hook (fix #9). The entry is cleared only once this session's pull has
  * succeeded AND there is no unpushed commit left behind by a failed push
  * (`[ahead N]`).
  *
@@ -280,6 +323,10 @@ let raw = '';
 process.stdin.setEncoding('utf-8');
 process.stdin.on('data', (chunk) => (raw += chunk));
 process.stdin.on('end', () => {
+  // ISSUE-5: declared before the try so every emit branch — including the outer
+  // catch — carries the same `systemMessage` (the user-visible update/sibling
+  // banner). Reassigned once below after the notices are computed.
+  let outExtra = { continue: true, suppressOutput: true };
   try {
     let data = {};
     try {
@@ -289,23 +336,33 @@ process.stdin.on('end', () => {
     const pullOk = gitPull(HYPO_DIR);
     const syncLine = syncStateNotice(pullOk);
     const growthLine = readLastGrowthLine();
-    // fix #25 PR-A2 (ADR 0022 amendment): on source='clear', surface the dying
+    // ADR 0022 amendment: on source='clear', surface the dying
     // session's identity that hypo-session-end stashed so Claude can recover
     // session-close work that /clear skipped. One-shot: marker is unlinked
     // immediately after read.
     const clearRecoveryLine = buildClearRecoveryLine(data.source);
     const updateLine = buildUpdateNotice();
-    // Intentional dual emit: stderr (yellow/cyan) is the human-visible nudge in
-    // the terminal; noticePrefix injects the same plain-text lines into the
-    // LLM's additionalContext so model and user start the session looking at
-    // the same state. ANSI escapes are kept out of additionalContext on purpose.
-    const notices = [syncLine, growthLine, clearRecoveryLine, updateLine].filter(Boolean);
+    const siblingLine = buildSiblingNotice();
+    // ISSUE-5: the update + stale-sibling banners must reach the USER. On a
+    // SessionStart hook that exits 0, stderr is invisible in the normal TUI
+    // (only shown on exit 2 / --verbose) and additionalContext is model-only —
+    // `systemMessage` is the documented user-visible channel. Route those two
+    // banners there. They ALSO stay in noticePrefix → additionalContext below,
+    // so the model and the user start the session looking at the same state.
+    // (The other stderr notices — sync/growth/clear/suggest — are intentionally
+    // transcript/--verbose only and out of ISSUE-5's scope.)
+    const userMessage = [updateLine, siblingLine].filter(Boolean).join('\n\n');
+    if (userMessage) outExtra = { ...outExtra, systemMessage: userMessage };
+    const notices = [syncLine, growthLine, clearRecoveryLine, updateLine, siblingLine].filter(
+      Boolean,
+    );
     let noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
     if (syncLine) process.stderr.write(`\n\x1b[33m${syncLine}\x1b[0m\n`);
     if (growthLine) process.stderr.write(`\n\x1b[36m${growthLine}\x1b[0m\n`);
     if (clearRecoveryLine)
       process.stderr.write(`\n\x1b[33m${clearRecoveryLine.split('\n')[0]}\x1b[0m\n`);
     if (updateLine) process.stderr.write(`\n\x1b[33m${updateLine}\x1b[0m\n`);
+    if (siblingLine) process.stderr.write(`\n\x1b[33m${siblingLine}\x1b[0m\n`);
     const cwd = data.cwd || data.directory || process.cwd();
     const sessionId = data.session_id || 'default';
     const MARKER_FILE = sessionMarkerPath(sessionId);
@@ -336,7 +393,7 @@ process.stdin.on('end', () => {
           JSON.stringify(
             buildOutput(
               `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}]\n\n${parts.join('\n\n')}`,
-              { continue: true, suppressOutput: true },
+              outExtra,
             ),
           ),
         );
@@ -352,10 +409,7 @@ process.stdin.on('end', () => {
           JSON.stringify(
             buildOutput(
               `${noticePrefix}[WIKI HOT CACHE: project=${sanitizeProjForPrompt(hit.proj)}, no snapshot yet]`,
-              {
-                continue: true,
-                suppressOutput: true,
-              },
+              outExtra,
             ),
           ),
         );
@@ -378,9 +432,9 @@ process.stdin.on('end', () => {
     if (!existsSync(GLOBAL_HOT)) {
       const notice = notices.join('\n\n');
       if (notice) {
-        console.log(JSON.stringify(buildOutput(notice, { continue: true, suppressOutput: true })));
+        console.log(JSON.stringify(buildOutput(notice, outExtra)));
       } else {
-        console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+        console.log(JSON.stringify(outExtra));
       }
       return;
     }
@@ -389,12 +443,12 @@ process.stdin.on('end', () => {
     if (!globalContent) {
       // GLOBAL_HOT exists but is empty or .hypoignore'd — still surface any
       // pending notices (sync state, growth, AND the auto-project offer), which
-      // would otherwise be silently dropped here (codex review 2026-05-22).
+      // would otherwise be silently dropped here.
       const notice = notices.join('\n\n');
       if (notice) {
-        console.log(JSON.stringify(buildOutput(notice, { continue: true, suppressOutput: true })));
+        console.log(JSON.stringify(buildOutput(notice, outExtra)));
       } else {
-        console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+        console.log(JSON.stringify(outExtra));
       }
       return;
     }
@@ -402,12 +456,12 @@ process.stdin.on('end', () => {
       JSON.stringify(
         buildOutput(
           `${noticePrefix}[WIKI HOT CACHE: global — no project matched cwd=${cwd}]\n\n${globalContent}`,
-          { continue: true, suppressOutput: true },
+          outExtra,
         ),
       ),
     );
   } catch (err) {
     process.stderr.write(`[hypo-session-start] error: ${err?.message ?? String(err)}\n`);
-    console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+    console.log(JSON.stringify(outExtra));
   }
 });

package/hooks/hypo-shared.mjs

@@ -17,8 +17,8 @@ const HOME = homedir();
 // hypo-session-start / hypo-cwd-change WRITE this marker; hypo-first-prompt
 // READS + unlinks it. The session_id comes from the Claude Code runtime (a
 // UUID), but we sanitize defensively so a malformed id with path separators or
-// `..` can never escape tmpdir or collide on an empty value (codex review
-// 2026-05-21, fix #3/#13). Non-alphanumeric chars collapse to `_`.
+// `..` can never escape tmpdir or collide on an empty value. Non-alphanumeric
+// chars collapse to `_`.
 export function sessionMarkerPath(sessionId) {
   const safe = String(sessionId || 'default').replace(/[^A-Za-z0-9._-]/g, '_') || 'default';
   return join(tmpdir(), `hypo-session-marker-${safe}.json`);
@@ -207,8 +207,8 @@ export function hasSessionLogHeading(content, date) {
  * "foo-bar" (hyphen is non-word). The canonical log format always separates the
  * project slug from anything that follows by whitespace or end-of-line, so the
  * lookahead correctly rejects "session | foo-bar" when looking for "foo".
- * (Reported by codex review of fix #38 — was a pre-existing bug in
- * sessionCloseFileStatus that the helper extraction inherited.)
+ * (Was a pre-existing bug in sessionCloseFileStatus that the helper extraction
+ * inherited.)
  */
 export function hasLogEntry(content, date, project) {
   return new RegExp(
@@ -232,13 +232,56 @@ export function freshDates() {
   return local === utc ? [local] : [local, utc];
 }
 
+// Parse a single frontmatter scalar (mirrors hypo-session-start.mjs /
+// hypo-cwd-change.mjs; local copy per the hook self-contained convention).
+function parseFrontmatterField(content, key) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const line = m[1].split('\n').find((l) => l.startsWith(`${key}:`));
+  if (!line) return null;
+  return line
+    .slice(key.length + 1)
+    .trim()
+    .replace(/^['"]|['"]$/g, '');
+}
+
+// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
+// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
+// when cwd is falsy or matches none. Used only as a same-date tie-breaker.
+function pickByCwd(hypoDir, slugs, cwd) {
+  if (!cwd) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const slug of slugs) {
+    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
+    if (!existsSync(indexPath)) continue;
+    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
+    if (!wd) continue;
+    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
+    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
+    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
+      bestLen = resolved.length;
+      best = slug;
+    }
+  }
+  return best;
+}
+
 /**
  * Resolve the most-recently-active project slug from root hot.md.
- * Mirrors scripts/resume.mjs resolveActiveProject — kept in sync by hand.
+ * The cwd helpers (parseFrontmatterField / pickByCwd) and the same-date
+ * tie-break are kept in sync with scripts/resume.mjs by hand; the surrounding
+ * wrapper intentionally differs (resume.mjs adds an mtime fallback, this does not).
+ * `cwd` is an optional same-date tie-breaker (ISSUE-1): resume passes
+ * process.cwd(); session-close callers (sessionCloseFileStatus /
+ * closeFileTargets) intentionally pass null — close has a different
+ * authority (payload.project / freshness), tracked separately as ISSUE-7.
+ * When cwd is omitted, behavior is identical to the legacy version.
  * @param {string} hypoDir
+ * @param {string|null} [cwd]
  * @returns {string|null}
  */
-export function resolveActiveProject(hypoDir) {
+export function resolveActiveProject(hypoDir, cwd = null) {
   const hotPath = join(hypoDir, 'hot.md');
   if (!existsSync(hotPath)) return null;
   let content;
@@ -257,6 +300,19 @@ export function resolveActiveProject(hypoDir) {
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
     wikiRows.sort((a, b) => b.date.localeCompare(a.date));
+    // Same-date tie-break (ISSUE-1): when the top date is shared by >1 row,
+    // prefer the project whose working_dir contains cwd. No cwd / no match →
+    // keep the stable-sort winner (the legacy "first table row" behavior).
+    const topDate = wikiRows[0].date;
+    const tied = wikiRows.filter((r) => r.date === topDate);
+    if (cwd && tied.length > 1) {
+      const picked = pickByCwd(
+        hypoDir,
+        tied.map((r) => r.slug),
+        cwd,
+      );
+      if (picked) return picked;
+    }
     return wikiRows[0].slug;
   }
   // Legacy markdown-link rows: | [name](projects/name/...) | ...
@@ -277,12 +333,21 @@ export function resolveActiveProject(hypoDir) {
  * project A can't be masked by a fresh close of project B (and vice versa).
  * open-questions.md (file #5) is conditional and not gated.
  *
+ * `projectOverride` (ISSUE-7 Part A): when the caller already holds the
+ * authoritative project being closed (e.g. crystallize apply derives it from
+ * `payload.project`), it passes that slug so verification checks the SAME
+ * project it just wrote — instead of re-deriving via resolveActiveProject(),
+ * which on a same-date root-hot.md tie can resolve a DIFFERENT project and
+ * false-fail a completed close. When omitted, behavior is byte-identical to the
+ * legacy single-arg version (resolve from root hot.md).
+ *
  * @param {string} hypoDir
+ * @param {{projectOverride?: string|null}} [opts]
  * @returns {{ok: boolean, project: string|null, dates: string[], stale: string[], missing: string[]}}
  */
-export function sessionCloseFileStatus(hypoDir) {
+export function sessionCloseFileStatus(hypoDir, { projectOverride = null } = {}) {
   const dates = freshDates();
-  const project = resolveActiveProject(hypoDir);
+  const project = projectOverride || resolveActiveProject(hypoDir);
   if (!project) {
     return {
       ok: false,
@@ -358,9 +423,9 @@ export function sessionCloseFileStatus(hypoDir) {
 
 // ── sync-state ────────────────────────────────────────────
 // `.cache/sync-state.json` is JSONL: one {timestamp, op, error, host} entry per
-// line. hypo-auto-commit (#9) appends on pull/push failure; hypo-session-start
-// (#10) surfaces open entries and clears them once sync is healthy again;
-// doctor (#11) warns while entries remain. Keep the schema defined here only.
+// line. hypo-auto-commit (fix #9) appends on pull/push failure; hypo-session-start
+// (fix #10) surfaces open entries and clears them once sync is healthy again;
+// doctor (fix #11) warns while entries remain. Keep the schema defined here only.
 
 /** @returns {string} path to the sync-state JSONL file for a wiki root. */
 function syncStatePath(hypoDir) {
@@ -527,14 +592,12 @@ export function shouldSuggestProjectCreation(cwd, hypoDir = HYPO_DIR, now = Date
  * Build the §8.11 auto-project offer line for a cwd. The display name is the
  * cwd basename, which is attacker-influenced (a directory name can contain
  * newlines/control chars on Unix). Strip control characters and length-cap it
- * so a crafted dir name cannot spoof extra instructions in additionalContext
- * (codex review 2026-05-22).
+ * so a crafted dir name cannot spoof extra instructions in additionalContext.
  */
 export function buildProjectSuggestionLine(cwd) {
   // Replace any control char (code < 0x20 or === 0x7F) with a space so a
-  // crafted dir name cannot inject newlines/instructions into additionalContext
-  // (codex review 2026-05-22). Done by codepoint to keep control bytes out of
-  // this source file.
+  // crafted dir name cannot inject newlines/instructions into additionalContext.
+  // Done by codepoint to keep control bytes out of this source file.
   const sanitized = Array.from(basename(cwd))
     .map((ch) => {
       const code = ch.codePointAt(0);
@@ -803,6 +866,133 @@ export function hasMutatingTranscriptActivity(transcriptPath) {
   return false;
 }
 
+// ── session-scoped lint classification ──────────────────────────────────────
+// Bug A/B fix: the close gate must judge a session on the files IT touched, not
+// the whole vault. Lint debt from another project/session (often in shared
+// pages/) must not block this session's close/compact. Two scope builders feed
+// one shared classifier: transcript-derived (hooks + standalone marker) and
+// close-file/payload-derived (the documented apply path writes via Bash, so its
+// files never appear as Edit/Write file_paths and must be seeded explicitly).
+
+const MUTATING_FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/** Pull file_path/notebook_path args from mutating tool_use blocks in one
+ *  transcript entry. Mirrors extractTranscriptToolNames' shape handling
+ *  (top-level tool_use + nested message.content[] blocks). */
+function extractTranscriptToolFilePaths(entry) {
+  const paths = [];
+  if (!entry || typeof entry !== 'object') return paths;
+  const pull = (name, input) => {
+    if (!name || !MUTATING_FILE_TOOLS.has(name) || !input || typeof input !== 'object') return;
+    const fp = input.file_path || input.notebook_path;
+    if (typeof fp === 'string' && fp) paths.push(fp);
+  };
+  if (entry.type === 'tool_use') pull(entry.name || entry.tool_name, entry.input);
+  const content = entry.message?.content ?? (Array.isArray(entry.content) ? entry.content : null);
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === 'object' && block.type === 'tool_use') {
+        pull(block.name || block.tool_name, block.input);
+      }
+    }
+  }
+  return paths;
+}
+
+/** Normalize an absolute path to a repo-relative POSIX path under hypoDir, or
+ *  null if it resolves outside the wiki. */
+function toHypoRel(absPath, hypoDir) {
+  let rel;
+  try {
+    rel = relative(hypoDir, absPath);
+  } catch {
+    return null;
+  }
+  if (!rel || rel.startsWith('..') || rel.startsWith('/')) return null;
+  return rel.split('\\').join('/');
+}
+
+/**
+ * Repo-relative POSIX paths of wiki files this session edited via direct
+ * Edit/Write/MultiEdit/NotebookEdit tool_use. Returns a Set; empty when the
+ * transcript is missing/unreadable (callers decide the fallback). A per-line
+ * JSON parse error skips that line only (transcripts occasionally truncate).
+ */
+export function extractTouchedWikiFiles(transcriptPath, hypoDir) {
+  const out = new Set();
+  if (!transcriptPath || typeof transcriptPath !== 'string' || !existsSync(transcriptPath)) {
+    return out;
+  }
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf-8');
+  } catch {
+    return out;
+  }
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let entry;
+    try {
+      entry = JSON.parse(t);
+    } catch {
+      continue;
+    }
+    for (const fp of extractTranscriptToolFilePaths(entry)) {
+      const rel = toHypoRel(fp, hypoDir);
+      if (rel) out.add(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * The mandatory session-close files (repo-relative POSIX). The documented close
+ * path `crystallize.mjs --apply-session-close` writes these from inside a Bash
+ * call, so they never surface as Edit/Write file_paths — they must seed the
+ * scoped-lint set explicitly or a close-introduced error would escape the gate.
+ * Mirrors the file list in sessionCloseFileStatus.
+ */
+export function closeFileTargets(hypoDir) {
+  const out = new Set(['hot.md', 'log.md']);
+  const project = resolveActiveProject(hypoDir);
+  if (project) {
+    out.add(`projects/${project}/session-state.md`);
+    out.add(`projects/${project}/hot.md`);
+    const month = freshDates()[0].slice(0, 7);
+    out.add(`projects/${project}/session-log/${month}.md`);
+  }
+  return out;
+}
+
+/** Normalize a path's separators to POSIX so scope membership is OS-independent.
+ *  lint.mjs emits `file` via path.relative (back-slashes on Windows) while the
+ *  scope builders produce forward-slash paths — normalize both sides. */
+function posixPath(p) {
+  return (p || '').split('\\').join('/');
+}
+
+/**
+ * Partition lint findings into `blocking` (a file this session is accountable
+ * for) vs `notice` (pre-existing debt elsewhere — surfaced, not blocking).
+ *
+ * `scope` = iterable of repo-relative paths the session is accountable for.
+ * Membership is exact on the normalized path. Only findings passed in are
+ * classified — callers pass lint ERRORS; broken wikilinks (lint W4 warnings) are
+ * intentionally warn-only (forward references to planned pages are normal in a
+ * wiki) and are NOT promoted to blocking by this gate.
+ */
+export function partitionLintScope(findings, scope) {
+  const normScope = new Set([...scope].map(posixPath));
+  const blocking = [];
+  const notice = [];
+  for (const f of findings || []) {
+    if (normScope.has(posixPath(f.file))) blocking.push(f);
+    else notice.push(f);
+  }
+  return { blocking, notice };
+}
+
 // ── session-close checklist ────────────────────────────────────────────────
 
 /**