hypomnema 1.7.0 → 1.7.2

package/hooks/hypo-close-guard.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * hypo-close-guard.mjs — PreToolUse hook
+ *
+ * SCOPE: this guard closes the direct Write/Edit/MultiEdit bypass only — it is
+ * not a general unauthorized-close catcher. A write executed via Bash (shell
+ * redirection, sed, a script) never reaches PreToolUse's tool_input inspection
+ * and is out of scope. The regular `/hypo:crystallize --apply-session-close`
+ * path runs via Bash and already validates the transcript's close signal
+ * before it writes, so it neither trips this guard nor needs to.
+ *
+ * Intercepts a Write/Edit/MultiEdit BEFORE it lands, when it targets one of the
+ * two close-artifact files (session-state.md, hot.md). doctor's
+ * detectSessionCloseArtifact (hypo-shared.mjs, post-hoc) only ever sees a file
+ * AFTER the write, and only fires on 마감/종료 vocabulary — a wordless full
+ * rewrite (the 2026-07-28 hot.md incident) reads clean to it, because there is
+ * no prior version to diff against.
+ *
+ * Here there is no such blind spot: the PRIMARY signal is structural, not
+ * lexical. recordTouchedPaths (populated by hypo-auto-stage's PostToolUse,
+ * which has already run for every earlier write this session) already tracks
+ * which close-artifact file(s) this session wrote. If the write in front of us
+ * targets one of a project's pair (projects/<slug>/session-state.md,
+ * projects/<slug>/hot.md) and the OTHER one is already in that set, this
+ * session is rewriting both — regardless of what either file's text says. The
+ * pair is scoped to the SAME project directory on purpose: pairing by basename
+ * alone would fire on the root hot.md (which every session's Stop-chain
+ * hypo-hot-rebuild.mjs legitimately rewrites) against an unrelated project's
+ * session-state.md — a false positive, not a close. Root hot.md is therefore
+ * never a structural pair member; it can still trip the lexical signal below
+ * if it is literally rewritten with 마감/종료 wording.
+ *
+ * KNOWN WINDOW: the structural signal is only alive for one turn. Stop's
+ * auto-commit chain (hypo-auto-commit.mjs → commitTouchedPaths) commits and
+ * then CLEARS a session's touched-paths set every time Stop runs. Write
+ * session-state.md in turn 1 and hot.md in turn 2 (Stop runs in between) and
+ * the touched-paths file no longer has the first path — structuralHit reads
+ * false. This is accepted, not fixed: a real close writes both files in the
+ * same turn (see the JSDoc coverage note in hypo-shared.mjs's
+ * detectSessionCloseArtifact), so the main path is still caught; a fresh
+ * cross-turn persistence store is out of this guard's scope. Once the window
+ * closes, only the lexical signal (detectSessionCloseArtifact on the write's
+ * own new text) can still catch a close. See the test that pins this window
+ * (using the real commitTouchedPaths path, not a bare drain) in
+ * tests/close-hooks-gate.test.mjs.
+ *
+ * CASE FOLDING: the basename gate and the structural pairing comparison below
+ * are lowercase-folded. macOS's default volume is case-insensitive, so a write
+ * to `projects/foo/HOT.md` targets the same file `hot.md` does, and comparing
+ * basenames verbatim would read it as "not a close-artifact file" and skip the
+ * structural check entirely. This folding covers only OUR OWN comparisons;
+ * detectSessionCloseArtifact (hypo-shared.mjs, untouched here) does its own
+ * case-sensitive basename check internally, so a case-varied write can still
+ * dodge the LEXICAL signal — but the structural signal does not depend on file
+ * content at all, so it still catches it.
+ *
+ * detectSessionCloseArtifact runs as a SECONDARY trigger regardless of the
+ * structural outcome, so a lone wordy close is caught before its pair even
+ * lands, and the two defenses share one definition of "close" instead of
+ * drifting apart.
+ *
+ * UNDECIDABLE vs BROKEN: the structural signal reads the session's
+ * touched-paths cache directly (readTouchedPathsOrUndecidable below), not via
+ * hypo-shared's peekTouchedPaths, because peekTouchedPaths collapses a lock
+ * timeout, a corrupt cache file, AND a genuinely-empty session into the exact
+ * same `[]` — indistinguishable from the caller's side. Folding all three into
+ * "no structural signal, allow" would let a wordless close slip through
+ * exactly when this guard's own bookkeeping is unreliable, which is the worst
+ * moment for it to go quiet. So an undecidable read (lock timeout / corrupt
+ * cache / no session_id) is instead treated as a HIT — it folds into the same
+ * `ask` branch as a genuine structural match. This is deliberately distinct
+ * from the hook ITSELF breaking (unparseable stdin, an unexpected exception):
+ * that still exits silently below, because a broken guard must never block
+ * the user's actual work. readTouchedPathsOrUndecidable is built from the same
+ * exported primitives peekTouchedPaths itself uses (withFileLock,
+ * touchedPathsPath) — no new read-only API was added to hypo-shared.mjs for
+ * this.
+ *
+ * NO EXPLICIT ALLOW: `permissionDecision: "allow"` is not "stay quiet" — it
+ * tells Claude Code to bypass the user's NORMAL permission prompt for this
+ * tool call outright. This hook has no matcher (see NO MATCHER below), so it
+ * runs in front of every tool call, Bash included; printing an explicit allow
+ * anywhere would auto-approve permission prompts this guard has no business
+ * touching, which is the opposite of what a "confirm before a close" guard is
+ * for. So every pass-through path below prints NOTHING and exits 0, leaving
+ * Claude Code's normal permission policy exactly as it was. Only a genuine
+ * `ask` hit ever writes to stdout.
+ *
+ * A hit is never a deny. The hook only ASKS
+ * (hookSpecificOutput.permissionDecision = "ask") — the harness turns that into
+ * a confirmation in front of the write; approval stays with the human.
+ *
+ * NO MATCHER: this hook is registered under PreToolUse with no matcher (this
+ * repo's installer does not carry matchers through to settings — see
+ * scripts/init.mjs's `_extractFileNames` — and no other hook here uses one
+ * either), so it runs on every tool call. The early-return order below exists
+ * for exactly that: a non-write tool, or a write outside HYPO_DIR, returns
+ * before anything else runs.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { relative } from 'path';
+import {
+  HYPO_DIR,
+  detectSessionCloseArtifact,
+  hasUserCloseSignal,
+  isGateSkipped,
+  touchedPathsPath,
+  withFileLock,
+} from './hypo-shared.mjs';
+
+const CLOSE_ARTIFACT_BASENAMES = new Set(['session-state.md', 'hot.md']);
+// Mirrors hypo-auto-stage.mjs's WRITE_TOOLS: the tools that replace file bytes.
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
+
+// The write's own new text. Write carries the whole file; Edit/MultiEdit carry
+// only the replaced snippet(s) — good enough for detectSessionCloseArtifact,
+// which matches a single bold heading line, not the whole document.
+function newTextOf(toolName, toolInput) {
+  if (toolName === 'Write') {
+    return typeof toolInput?.content === 'string' ? toolInput.content : '';
+  }
+  if (toolName === 'Edit') {
+    return typeof toolInput?.new_string === 'string' ? toolInput.new_string : '';
+  }
+  if (toolName === 'MultiEdit' && Array.isArray(toolInput?.edits)) {
+    return toolInput.edits
+      .map((e) => (typeof e?.new_string === 'string' ? e.new_string : ''))
+      .join('\n');
+  }
+  return '';
+}
+
+// See "UNDECIDABLE vs BROKEN" above. `{ok: true, paths}` on a clean read
+// (including a genuinely absent file — never touched this session, not an
+// error); `{ok: false}` when the read cannot be trusted (no session_id, a
+// corrupt/non-array cache file, or a lock timeout).
+function readTouchedPathsOrUndecidable(hypoDir, sessionId) {
+  if (!sessionId) return { ok: false };
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      if (!existsSync(path)) return { ok: true, paths: [] };
+      try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!Array.isArray(parsed)) return { ok: false }; // corrupt shape
+        return { ok: true, paths: parsed.filter((p) => typeof p === 'string' && p) };
+      } catch {
+        return { ok: false }; // corrupt/unreadable JSON
+      }
+    });
+  } catch {
+    return { ok: false }; // lock timeout
+  }
+}
+
+let input = {};
+try {
+  const raw = await new Promise((r) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => r(d));
+  });
+  input = JSON.parse(raw);
+} catch (err) {
+  // The hook ITSELF failed to read its own input — stay silent (see NO
+  // EXPLICIT ALLOW above); never write a permission decision over garbage.
+  process.stderr.write(`[hypo-close-guard] error: ${err?.message ?? String(err)}\n`);
+  process.exit(0);
+}
+
+try {
+  if (isGateSkipped() || !WRITE_TOOLS.has(input.tool_name)) {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path ?? '';
+  if (!filePath || !(filePath === HYPO_DIR || filePath.startsWith(HYPO_DIR + '/'))) {
+    process.exit(0);
+  }
+
+  const rel = relative(HYPO_DIR, filePath);
+  const relParts = rel.split(/[\\/]/);
+  const base = relParts[relParts.length - 1];
+  const baseLower = base.toLowerCase();
+  if (!CLOSE_ARTIFACT_BASENAMES.has(baseLower)) {
+    process.exit(0);
+  }
+
+  // Structural signal (primary): the OTHER close-artifact file of the SAME
+  // project already written this session — projects/<slug>/session-state.md
+  // paired with projects/<slug>/hot.md ONLY (case-folded). A root hot.md
+  // (relParts.length !== 3, or not under "projects/") is never a pair member.
+  const otherBaseLower = baseLower === 'hot.md' ? 'session-state.md' : 'hot.md';
+  let structuralHit = false;
+  let structuralUndecidable = false;
+  if (relParts.length === 3 && relParts[0].toLowerCase() === 'projects') {
+    const otherPathLower = `${relParts[0].toLowerCase()}/${relParts[1].toLowerCase()}/${otherBaseLower}`;
+    const touchedResult = readTouchedPathsOrUndecidable(HYPO_DIR, input.session_id);
+    if (!touchedResult.ok) {
+      structuralUndecidable = true; // see "UNDECIDABLE vs BROKEN" above
+    } else {
+      structuralHit = touchedResult.paths.some((p) => p.toLowerCase() === otherPathLower);
+    }
+  }
+
+  // Lexical signal (secondary): same predicate doctor uses post-hoc, run here
+  // on the write's own new text.
+  const lexicalHit = detectSessionCloseArtifact({
+    path: filePath,
+    content: newTextOf(input.tool_name, input.tool_input),
+  }).matched;
+
+  if (!structuralHit && !structuralUndecidable && !lexicalHit) {
+    process.exit(0);
+  }
+
+  if (hasUserCloseSignal(input.transcript_path ?? null)) {
+    process.exit(0);
+  }
+
+  const why = structuralUndecidable
+    ? `whether session-state.md and hot.md are both being rewritten this session could not be determined (touched-paths cache unreadable or no session_id)`
+    : structuralHit
+      ? `both session-state.md and hot.md are being rewritten this session`
+      : `this write reads as a close announcement (마감/종료 wording)`;
+
+  console.log(
+    JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason:
+          `[WIKI CLOSE GUARD] ${rel} — ${why}, but no user close signal was seen ` +
+          `in this session. Confirm with the user before writing: did they actually ` +
+          `ask to close the session?\n` +
+          `To bypass: set HYPO_SKIP_GATE=1`,
+      },
+    }),
+  );
+} catch (err) {
+  // The hook ITSELF broke (unexpected exception) — stay silent, same as the
+  // stdin-parse failure above: a broken guard must never block real work.
+  process.stderr.write(`[hypo-close-guard] error: ${err?.message ?? String(err)}\n`);
+}

package/hooks/hypo-hot-rebuild.mjs

@@ -17,11 +17,31 @@ import {
   computeSessionGrowth,
   formatGrowthMetrics,
   deriveRootLogEntries,
+  recordTouchedPaths,
 } from './hypo-shared.mjs';
 
 const HOT_PATH = join(HYPO_DIR, 'hot.md');
 const GROWTH_CACHE = join(HYPO_DIR, '.cache', 'last-session-growth.json');
 
+// This Stop hook runs BEFORE hypo-auto-commit and can write hot.md
+// (rebuild) and log.md (deriveRootLogEntries), both hook-generated, not user
+// Write/Edit, so hypo-auto-stage never sees them. Read session_id off stdin so
+// whatever this hook writes still lands in the scoped commit's set; without
+// this, a scope built from Write/Edit alone would silently drop these files
+// from every session's auto-commit.
+let sessionId = null;
+try {
+  const raw = await new Promise((r) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => r(d));
+  });
+  const payload = JSON.parse(raw || '{}') || {};
+  sessionId = payload.session_id || payload.sessionId || null;
+} catch {
+  sessionId = null;
+}
+
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return {};
@@ -52,12 +72,13 @@ function parsePointerRows(content) {
   return rows;
 }
 
+/** @returns {boolean} true when hot.md was actually rewritten. */
 function rebuild() {
-  if (!existsSync(HOT_PATH)) return;
+  if (!existsSync(HOT_PATH)) return false;
 
   const current = readFileSync(HOT_PATH, 'utf-8');
   const rows = parsePointerRows(current);
-  if (rows.length === 0) return;
+  if (rows.length === 0) return false;
 
   const today = new Date().toISOString().slice(0, 10);
 
@@ -93,7 +114,11 @@ ${tableRows}
 3. Read \`projects/<name>/hot.md\` for project background
 `;
 
-  if (canonical !== current) writeFileSync(HOT_PATH, canonical);
+  if (canonical !== current) {
+    writeFileSync(HOT_PATH, canonical);
+    return true;
+  }
+  return false;
 }
 
 function emitGrowth() {
@@ -107,16 +132,18 @@ function emitGrowth() {
   } catch {}
 }
 
+let hotWritten = false;
 try {
-  rebuild();
+  hotWritten = rebuild();
 } catch (err) {
   process.stderr.write(`[hypo-hot-rebuild] error: ${err?.message ?? String(err)}\n`);
 }
 // Auto-derive the root log.md session entry from each project's session-log
 // heading (runs AFTER rebuild() so root hot.md is already fresh and isn't itself
 // counted as the project's open gate problem). Best-effort: own try/catch.
+let logEntriesAdded = 0;
 try {
-  deriveRootLogEntries(HYPO_DIR);
+  logEntriesAdded = deriveRootLogEntries(HYPO_DIR);
 } catch (err) {
   process.stderr.write(`[hypo-hot-rebuild] log-derive error: ${err?.message ?? String(err)}\n`);
 }
@@ -126,6 +153,17 @@ try {
   process.stderr.write(`[hypo-hot-rebuild] error: ${err?.message ?? String(err)}\n`);
 }
 
+// Feed this hook's own writes into the session's scoped auto-commit
+// set (see the sessionId comment above). No-op without a session_id.
+try {
+  const touched = [];
+  if (hotWritten) touched.push('hot.md');
+  if (logEntriesAdded > 0) touched.push('log.md');
+  if (touched.length > 0) recordTouchedPaths(HYPO_DIR, sessionId, touched);
+} catch (err) {
+  process.stderr.write(`[hypo-hot-rebuild] touched-paths error: ${err?.message ?? String(err)}\n`);
+}
+
 try {
   console.log(JSON.stringify({ continue: true, suppressOutput: true }));
 } catch {}

package/hooks/hypo-session-start.mjs

@@ -19,6 +19,8 @@ import {
   formatGrowthMetrics,
   readSyncState,
   clearSyncState,
+  recordSyncSuccess,
+  classifySyncOp,
   readClearMarker,
   clearClearMarker,
   loadHypoIgnore,
@@ -35,6 +37,8 @@ import {
   currentDevice,
   scopeVisible,
   readVisibilityScope,
+  pkgRootDriftStatus,
+  PKG_ROOT,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -48,6 +52,12 @@ import {
   computeSiblingNotice,
   siblingAlreadyNotified,
   markSiblingNotified,
+  pkgRootDriftAlreadyNotified,
+  markPkgRootDriftNotified,
+  clearPkgRootDriftNotified,
+  pkgRootNullAlreadyNotified,
+  markPkgRootNullNotified,
+  clearPkgRootNullNotified,
 } from './version-check.mjs';
 import { snapshotBase, overwriteTargets } from './base-store.mjs';
 import { listProposals } from './proposal-store.mjs';
@@ -214,6 +224,94 @@ function buildSiblingNotice() {
   }
 }
 
+/**
+ * pkgRoot drift notice. hypo-shared.mjs's resolvePkgRoot() already
+ * self-corrects PKG_ROOT in memory whenever the code's own resolved location
+ * disagrees with the cached hypo-pkg.json — but silent self-correction is the
+ * exact failure this closes: the user's own `upgrade` habit stops mattering
+ * and nothing ever tells them hypo-pkg.json fell behind. Surfaced once per
+ * (cached → self-location) pair via the same notify-once cache the sibling
+ * notice above uses — a fresh drift (new self-location) re-notifies, but
+ * staying on the same drifted state doesn't nag every session.
+ *
+ * Tri-state (pkgRootDriftStatus): 'match' CLEARS any earlier mark (checked
+ * FIRST, unconditionally — even under opt-out, so a drift that resolves while
+ * opted out doesn't leave a stale mark that then suppresses a genuine
+ * recurrence once opt-out is lifted); 'unknown' touches nothing (self-location
+ * could not be resolved this session — the permanent steady state for the
+ * npm/manual channel, not evidence either way); only 'drift' can produce a
+ * banner, and opt-out is checked there so an opted-out session never marks a
+ * pair as notified it never actually showed.
+ */
+function buildPkgRootDriftNotice() {
+  try {
+    const status = pkgRootDriftStatus();
+    const cachePath = defaultCachePath();
+    if (status.status === 'match') {
+      clearPkgRootDriftNotified(cachePath);
+      return '';
+    }
+    if (status.status === 'unknown') return '';
+    if (isOptedOut()) return '';
+    const key = `${status.cached || '(none)'}->${status.self}`;
+    const cache = readCache(cachePath);
+    if (pkgRootDriftAlreadyNotified(cache, key)) return '';
+    markPkgRootDriftNotified(cachePath, key);
+    return (
+      `[Hypomnema] Package metadata drift: hypo-pkg.json still points at ` +
+      `\`${status.cached || '(none)'}\`, but the code actually running resolves to ` +
+      `\`${status.self}\`.\n` +
+      `  Hooks already resolved the correct root for this session — this is a ` +
+      `heads-up, not a blocker.\n` +
+      `  → run \`/hypo:upgrade --apply\` to bring hypo-pkg.json back in sync.`
+    );
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * PKG_ROOT-null notice. A different failure than the drift banner above:
+ * drift only fires when self-location DID resolve (PKG_ROOT is non-null,
+ * just disagreeing with the cache). This fires when hooks/hypo-shared.mjs's
+ * resolvePkgRoot() came up with nothing at all — self-location failed AND no
+ * verified provenance sidecar covered it — which is exactly the state where
+ * PreCompact's lint/feedback calls silently no-op (they have no root to
+ * shell scripts through). The two conditions cannot both hold in the same
+ * session (drift requires a non-null self-location), so there is no overlap
+ * to arbitrate — they use separate notify-once cache fields regardless, so
+ * neither one depends on that being true forever.
+ *
+ * Same notify-once shape as the drift banner: shown once, cleared as soon as
+ * PKG_ROOT resolves again so a later recurrence re-notifies instead of
+ * staying suppressed by a mark from a different install state.
+ */
+function buildPkgRootNullNotice() {
+  try {
+    const cachePath = defaultCachePath();
+    if (PKG_ROOT) {
+      clearPkgRootNullNotified(cachePath);
+      return '';
+    }
+    if (isOptedOut()) return '';
+    const cache = readCache(cachePath);
+    if (pkgRootNullAlreadyNotified(cache)) return '';
+    markPkgRootNullNotified(cachePath);
+    return (
+      `[Hypomnema] Package root unresolved: this install's hooks cannot locate ` +
+      `their own package, so PreCompact's lint/feedback checks are silently ` +
+      `skipped this session.\n` +
+      `  → run \`hypomnema upgrade --apply\` to sync this install's hook copies ` +
+      `with the current package (the \`/hypo:upgrade --apply\` slash command does ` +
+      `the same thing, where slash commands were installed). \`/hypo:init\` will ` +
+      `NOT fix this — it skips every hook file that already exists.\n` +
+      `  → or run \`hypomnema doctor\` to see what's missing.`
+    );
+  } catch {
+    return '';
+  }
+}
+
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
 const GROWTH_CACHE = join(HYPO_DIR, '.cache', 'last-session-growth.json');
 
@@ -253,14 +351,22 @@ function buildClearRecoveryLine(source) {
   );
 }
 
-/** Pull the wiki repo. Returns true only when the pull actually succeeded. */
+/**
+ * Pull the wiki repo. Returns true only when the pull actually succeeded. On
+ * success, also records the last-success timestamp (silently — no notice; the
+ * existing failure notice below is unchanged) so doctor never reports "never
+ * synced" right after a healthy startup pull, even when no auto-commit Stop
+ * hook has run yet this session.
+ */
 function gitPull(dir) {
   if (!existsSync(join(dir, '.git'))) return false;
   const r = spawnSync('git', ['-C', dir, 'pull', '--ff-only', '--quiet'], {
     stdio: 'pipe',
     timeout: 10000,
   });
-  return r.status === 0;
+  const ok = r.status === 0;
+  if (ok) recordSyncSuccess(dir, 'pull');
+  return ok;
 }
 
 /**
@@ -274,7 +380,9 @@ function gitPull(dir) {
  * fresh `hypo init` wiki does not git-ignore `.cache/`, so a broader cleanliness
  * check would see the sync-state file itself and never clear.
  *
- * @returns {string} a `[WIKI: last sync failed: ...]` line, or '' when clear.
+ * @returns {string} a `[WIKI: last sync failed: ...]` (or, for a conflict/
+ *   conflict-unresolved entry, dedicated manual-merge guidance) line, or ''
+ *   when clear.
  */
 function syncStateNotice(pullOk) {
   const { entries, parseError } = readSyncState(HYPO_DIR);
@@ -295,13 +403,44 @@ function syncStateNotice(pullOk) {
     return '';
   }
   const last = entries[entries.length - 1];
-  if (last.op === 'conflict') {
+  // classifySyncOp (hypo-shared.mjs) is the single judgment both this hook
+  // and doctor.mjs's checkSyncState branch on, so the two surfaces cannot
+  // silently diverge on WHICH op gets which treatment: this exact check used
+  // to be an exact `=== 'conflict'` comparison here that missed
+  // 'conflict-unresolved' — the MORE dangerous op, since the abort itself
+  // failed and the tree may still be half-merged — while doctor already
+  // caught it via startsWith('conflict').
+  const cls = classifySyncOp(last.op);
+  if (cls === 'conflict-unresolved') {
+    return (
+      `[WIKI: remote diverged AND the automatic merge-abort failed — the working ` +
+      `tree may still be half-merged (unmerged paths or an in-progress merge). ` +
+      `Do NOT commit or push yet. Inspect \`git -C ${HYPO_DIR} status\` first: if a ` +
+      `merge is in progress, resolve the conflicts, then \`git -C ${HYPO_DIR} add <resolved paths>\` ` +
+      `and \`git -C ${HYPO_DIR} commit\` (git refuses a commit while unmerged entries remain staged) ` +
+      `— or run \`git -C ${HYPO_DIR} merge --abort\` to discard it instead, before continuing.]`
+    );
+  }
+  if (cls === 'conflict') {
     return (
       `[WIKI: remote diverged — auto-merge was aborted to protect your edits ` +
       `(your local work is committed and safe; the other machine's version is on the remote). ` +
       `Resolve manually: \`git -C ${HYPO_DIR} pull --no-rebase\`, fix conflicts, then push.]`
     );
   }
+  // An unrecognized `conflict*` op — some future syncRemote failure mode this
+  // hook has no dedicated branch for. Neither the clean-conflict claim above
+  // ("committed and safe") nor the conflict-unresolved claim ("the abort
+  // failed") is known to be true here, so assert neither: say plainly that
+  // the state is unknown and treat it as unresolved until a human checks.
+  if (cls === 'unknown-conflict') {
+    return (
+      `[WIKI: remote diverged — an unrecognized conflict-related sync failure was recorded ` +
+      `(op='${last.op}'). Its resolution state cannot be confirmed automatically, so treat it ` +
+      `as unresolved: do NOT commit or push yet. Inspect \`git -C ${HYPO_DIR} status\` first for ` +
+      `unmerged paths or an in-progress merge before continuing.]`
+    );
+  }
   return `[WIKI: last sync failed: ${last.op || '?'} — ${last.error || 'unknown'}]`;
 }
 /**
@@ -406,15 +545,25 @@ process.stdin.on('end', () => {
     const clearRecoveryLine = buildClearRecoveryLine(data.source);
     const updateLine = buildUpdateNotice();
     const siblingLine = buildSiblingNotice();
-    // 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 this banner's scope.)
-    const userMessage = [updateLine, siblingLine].filter(Boolean).join('\n\n');
+    const pkgDriftLine = buildPkgRootDriftNotice();
+    // pkgDriftLine and pkgNullLine can never both be non-empty in the same
+    // session: drift requires PKG_ROOT to have resolved (non-null) via
+    // self-location, while the null notice fires exactly when it did not.
+    // Listed together below on that basis, not because one is chosen over
+    // the other.
+    const pkgNullLine = buildPkgRootNullNotice();
+    // The update + stale-sibling + pkgRoot-drift/null 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 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 this banner's scope.)
+    const userMessage = [updateLine, siblingLine, pkgDriftLine, pkgNullLine]
+      .filter(Boolean)
+      .join('\n\n');
     if (userMessage) outExtra = { ...outExtra, systemMessage: userMessage };
     const notices = [
       syncLine,
@@ -423,6 +572,8 @@ process.stdin.on('end', () => {
       clearRecoveryLine,
       updateLine,
       siblingLine,
+      pkgDriftLine,
+      pkgNullLine,
     ].filter(Boolean);
     let noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
     if (syncLine) process.stderr.write(`\n\x1b[33m${syncLine}\x1b[0m\n`);
@@ -432,6 +583,8 @@ process.stdin.on('end', () => {
       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`);
+    if (pkgDriftLine) process.stderr.write(`\n\x1b[33m${pkgDriftLine}\x1b[0m\n`);
+    if (pkgNullLine) process.stderr.write(`\n\x1b[33m${pkgNullLine}\x1b[0m\n`);
     const cwd = data.cwd || data.directory || process.cwd();
     const sessionId = data.session_id || 'default';
     const MARKER_FILE = sessionMarkerPath(sessionId);