hypomnema 1.8.4 → 1.9.0

package/hooks/base-store.mjs

@@ -29,19 +29,26 @@
 // Everything here is best-effort: a hook must never fail a session start because
 // a cache write did not land. Read failures degrade to "base unknown", which the
 // caller treats as fail-safe (proposal), never as "no conflict".
+//
+// Every mutator below (snapshotBase, advanceBase, advanceBaseForWrite,
+// beginObservedGeneration, recordObserved, recordAppliedHash, clearAppliedHash,
+// advanceBaseAndRecordApplied) wraps its read-modify-write in `withFileLock`
+// (review r5-w3 major 1): SessionStart, a PostToolUse hand-edit hook, and
+// crystallize's own apply can all touch the SAME session's base.json around the
+// same time, and a plain `readBaseFile` → mutate → `atomicWrite` sequence with
+// no lock lets a later writer's read start before an earlier writer's write
+// lands, so the later one then republishes the whole file from its stale copy and
+// silently reverts the earlier writer's field. `atomicWrite`'s rename already
+// guarantees a reader never sees a torn/partial file, so this lock exists for
+// lost-update races between writers, not for read tearing. A lock timeout
+// degrades to the same fail-safe as any other write failure here: the field
+// that could not be recorded is simply left as it was.
 
 import { createHash } from 'node:crypto';
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-  renameSync,
-  closeSync,
-  openSync,
-  writeSync,
-} from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, closeSync, openSync, writeSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
+import { withFileLock } from './hypo-shared.mjs';
 
 /** sha256 of a UTF-8 string, hex. */
 export function hashContent(content) {
@@ -68,14 +75,6 @@ export function basePath(hypoDir, sessionId) {
   return join(hypoDir, '.cache', 'sessions', String(sessionId), 'base.json');
 }
 
-/** Atomic overwrite via tmp+rename, mirroring crystallize's atomicWrite. */
-function atomicWrite(path, content) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
-  writeFileSync(tmp, content);
-  renameSync(tmp, path);
-}
-
 /** Read and parse base.json. Returns null when absent, unreadable, or malformed. */
 function readBaseFile(hypoDir, sessionId) {
   const path = basePath(hypoDir, sessionId);
@@ -91,55 +90,133 @@ function readBaseFile(hypoDir, sessionId) {
 }
 
 /**
- * Snapshot the observed base hashes for `relPaths`, ONCE per session.
+ * Snapshot the observed base hashes for `relPaths`, ONCE PER KEY per session.
  *
  * Existence-check (invariant 1): when base.json already exists for this session,
- * this is a no-op: resume and compact must not move the base.
+ * an already-tracked key never moves: resume and compact must not move the
+ * base for a target this session has already seen.
+ *
+ * Late enrollment: `relPaths` can differ across calls in the SAME session. The
+ * caller that motivated this (hypo-session-start.mjs) resolves the project from
+ * `cwd`, which can miss on the session's first SessionStart and hit on a later
+ * resume or compact with the SAME session_id. `overwriteTargets(project)`
+ * then names two more paths than the first call did. Without this, those two
+ * targets would never get a key at all for the rest of the session (not even
+ * an 'unknown' one): `advanceBaseForWrite` and `recordObserved` are both
+ * scoped to `hasOwnProperty`, so an untracked key can never accept a write's
+ * provenance, and close falls back to `base-unknown` forever. So a key this
+ * call names that the session has NOT already seen is added now, hashed off
+ * disk exactly like a fresh snapshot's targets are; a key already tracked,
+ * present or 'absent', is left exactly as it was.
  *
  * A target that does not exist on disk is recorded as `null` (observed-absent),
  * which is distinct from having no entry at all (observed-nothing). Close treats
  * the first as "I saw no file, creating it is safe" and the second as fail-safe.
  *
+ * `knownHashes` (review r5-w3 blocker 1): for a `relPath` this map covers, its
+ * value is written as the base AS-IS (a hex hash, or `null` for observed-absent)
+ * instead of a fresh `hashFile` disk read. Late enrollment (see above) is the
+ * caller that needs this: hypo-session-start.mjs's HIT branch reads
+ * `hit.hotPath`/`hit.statePath` to decide what to SHOW the model, then calls
+ * this function to enroll those same two targets. Root targets are always
+ * snapshotted first (line ~999 there), so `path` already exists by the time the
+ * HIT branch's own call lands here, which used to always take the "enroll"
+ * branch below and re-read disk fresh: a SEPARATE read from the one whose
+ * bytes the model was just shown. Between those two reads, another writer can
+ * change the file: the base would then describe bytes the model never saw, and
+ * a close that reapplies a payload built from the shown bytes reads
+ * disk-equals-base and overwrites the intervening write with no park. Passing
+ * the hash of the exact bytes just shown closes that window: the base can only
+ * ever describe what this session was actually shown, never a bystander read.
+ * A `relPath` NOT in `knownHashes` still gets the old fresh-disk-read behavior
+ * (the root-only call above has no "shown bytes" to pin to, since it runs
+ * before any injection decision).
+ *
  * @param {string} hypoDir
  * @param {string} sessionId
  * @param {string[]} relPaths vault-relative target paths
- * @returns {{created: boolean, reason?: string}}
+ * @param {Record<string, string|null>|null} [knownHashes] exact-bytes hash (or
+ *   `null` for observed-absent) to record for a `relPath`, bypassing the disk
+ *   re-read that would otherwise risk racing a concurrent writer
+ * @returns {{created: boolean, reason?: string, enrolled?: string[]}}
  */
-export function snapshotBase(hypoDir, sessionId, relPaths) {
+export function snapshotBase(hypoDir, sessionId, relPaths, knownHashes = null) {
   if (!sessionId) return { created: false, reason: 'no-session-id' };
   const path = basePath(hypoDir, sessionId);
-  if (existsSync(path)) return { created: false, reason: 'already-snapshotted' };
+  // A hash this call was TOLD to use always wins over a disk read: `undefined`
+  // (unreadable) is the disk-read fallback's own "leave this key out" signal, so
+  // it must never mask an explicit known value.
+  const resolveHash = (rel) =>
+    knownHashes && Object.prototype.hasOwnProperty.call(knownHashes, rel)
+      ? knownHashes[rel]
+      : hashFile(join(hypoDir, rel));
 
-  const targets = {};
-  for (const rel of relPaths) {
-    if (!rel) continue;
-    const h = hashFile(join(hypoDir, rel));
-    // `undefined` (unreadable) is left OUT of the map on purpose: no entry means
-    // "unknown", and close fails safe into a proposal rather than assuming a
-    // file it could not read was unchanged.
-    if (h !== undefined) targets[rel] = h;
-  }
+  try {
+    // Whole function under one lock (major 1, review r5-w3): the "does path
+    // exist" branch below and the write that follows it must not interleave
+    // with another RMW on this same session's base.json (resume, compact, and
+    // this session's own close can all touch it concurrently).
+    return withFileLock(path, () => {
+      if (existsSync(path)) {
+        const parsed = readBaseFile(hypoDir, sessionId);
+        // Unreadable/malformed base.json: nothing safe to enroll into, same
+        // fallback the pre-enrollment code always gave for an existing file.
+        if (!parsed) return { created: false, reason: 'already-snapshotted' };
+        const missing = (relPaths || []).filter(
+          (rel) => rel && !Object.prototype.hasOwnProperty.call(parsed.targets, rel),
+        );
+        if (missing.length === 0) return { created: false, reason: 'already-snapshotted' };
+        for (const rel of missing) {
+          const h = resolveHash(rel);
+          if (h !== undefined) parsed.targets[rel] = h;
+        }
+        try {
+          atomicWrite(path, JSON.stringify(parsed, null, 2));
+          return { created: false, reason: 'enrolled', enrolled: missing };
+        } catch (e) {
+          return { created: false, reason: `write-failed: ${e && e.message}` };
+        }
+      }
 
-  const body = JSON.stringify(
-    { session_id: String(sessionId), created_at: new Date().toISOString(), targets },
-    null,
-    2,
-  );
+      const targets = {};
+      for (const rel of relPaths) {
+        if (!rel) continue;
+        const h = resolveHash(rel);
+        // `undefined` (unreadable) is left OUT of the map on purpose: no entry
+        // means "unknown", and close fails safe into a proposal rather than
+        // assuming a file it could not read was unchanged.
+        if (h !== undefined) targets[rel] = h;
+      }
 
-  try {
-    mkdirSync(dirname(path), { recursive: true });
-    // Exclusive create IS the existence-check, closing the gap between the
-    // existsSync above and the write below when two hooks race on one session.
-    const fd = openSync(path, 'wx');
-    try {
-      writeSync(fd, body);
-    } finally {
-      closeSync(fd);
-    }
-    return { created: true };
+      const body = JSON.stringify(
+        { session_id: String(sessionId), created_at: new Date().toISOString(), targets },
+        null,
+        2,
+      );
+
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        // Exclusive create IS the existence-check, closing the gap between the
+        // existsSync above and the write below when two hooks race on one
+        // session. Redundant with the outer lock now, kept as a second,
+        // cheaper guard: it costs nothing when the lock already serialized us.
+        const fd = openSync(path, 'wx');
+        try {
+          writeSync(fd, body);
+        } finally {
+          closeSync(fd);
+        }
+        return { created: true };
+      } catch (e) {
+        if (e && e.code === 'EEXIST') return { created: false, reason: 'already-snapshotted' };
+        // best-effort: a hook must never break a session start over a cache write
+        return { created: false, reason: `write-failed: ${e && e.message}` };
+      }
+    });
   } catch (e) {
-    if (e && e.code === 'EEXIST') return { created: false, reason: 'already-snapshotted' };
-    // best-effort: a hook must never break a session start over a cache write
+    // withFileLock throws on timeout/failure to acquire: best-effort, same as
+    // every other outcome here: a hook must never break a session start over
+    // a cache write.
     return { created: false, reason: `write-failed: ${e && e.message}` };
   }
 }
@@ -182,12 +259,19 @@ export function readBaseEntry(hypoDir, sessionId, relPath) {
  */
 export function advanceBase(hypoDir, sessionId, relPath, hash) {
   if (!sessionId) return false;
-  const parsed = readBaseFile(hypoDir, sessionId);
-  if (!parsed) return false;
-  parsed.targets[relPath] = hash;
+  const path = basePath(hypoDir, sessionId);
   try {
-    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
-    return true;
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      parsed.targets[relPath] = hash;
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   } catch {
     return false;
   }
@@ -234,17 +318,24 @@ export function advanceBase(hypoDir, sessionId, relPath, hash) {
  */
 export function advanceBaseForWrite(hypoDir, sessionId, relPath, absPath, knownHash = null) {
   if (!sessionId) return false;
-  const parsed = readBaseFile(hypoDir, sessionId);
-  if (!parsed) return false;
-  // Only a tracked target advances. hasOwnProperty, not truthiness: an
-  // observed-absent entry is `null` but still a legitimate key to advance from.
-  if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
-  const hash = typeof knownHash === 'string' ? knownHash : hashFile(absPath);
-  if (typeof hash !== 'string') return false; // absent/unreadable → leave base as-is
-  parsed.targets[relPath] = hash;
+  const path = basePath(hypoDir, sessionId);
   try {
-    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
-    return true;
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      // Only a tracked target advances. hasOwnProperty, not truthiness: an
+      // observed-absent entry is `null` but still a legitimate key to advance from.
+      if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
+      const hash = typeof knownHash === 'string' ? knownHash : hashFile(absPath);
+      if (typeof hash !== 'string') return false; // absent/unreadable → leave base as-is
+      parsed.targets[relPath] = hash;
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   } catch {
     return false;
   }
@@ -300,13 +391,20 @@ export function advanceBaseForWrite(hypoDir, sessionId, relPath, absPath, knownH
  */
 export function beginObservedGeneration(hypoDir, sessionId) {
   if (!sessionId) return false;
-  const parsed = readBaseFile(hypoDir, sessionId);
-  if (!parsed) return false;
-  const current = typeof parsed.observedGeneration === 'number' ? parsed.observedGeneration : 0;
-  parsed.observedGeneration = current + 1;
+  const path = basePath(hypoDir, sessionId);
   try {
-    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
-    return true;
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      const current = typeof parsed.observedGeneration === 'number' ? parsed.observedGeneration : 0;
+      parsed.observedGeneration = current + 1;
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   } catch {
     return false;
   }
@@ -326,7 +424,7 @@ export function beginObservedGeneration(hypoDir, sessionId) {
  * refuses to hand it out as a licence: seeing 5% of a file is not seeing it.
  *
  * No-op, in order: no snapshot for this session; `relPath` is not one of the
- * four tracked overwrite targets (mirrors `advanceBaseForWrite`'s scoping —
+ * tracked overwrite targets (mirrors `advanceBaseForWrite`'s scoping --
  * this must not be able to mint a new guarded key). Stamped with the CURRENT
  * `observedGeneration`, never advancing it: the caller advances once via
  * `beginObservedGeneration`, not once per recorded target.
@@ -345,18 +443,30 @@ function safeGeneration(v) {
 
 export function recordObserved(hypoDir, sessionId, relPath, hash, truncated = false) {
   if (!sessionId) return false;
-  const parsed = readBaseFile(hypoDir, sessionId);
-  if (!parsed) return false;
-  if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
-  if (typeof hash !== 'string') return false;
-  const generation = typeof parsed.observedGeneration === 'number' ? parsed.observedGeneration : 0;
-  if (!parsed.observed || typeof parsed.observed !== 'object' || Array.isArray(parsed.observed)) {
-    parsed.observed = {};
-  }
-  parsed.observed[relPath] = { generation, hash, truncated: !!truncated };
+  const path = basePath(hypoDir, sessionId);
   try {
-    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
-    return true;
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
+      if (typeof hash !== 'string') return false;
+      const generation =
+        typeof parsed.observedGeneration === 'number' ? parsed.observedGeneration : 0;
+      if (
+        !parsed.observed ||
+        typeof parsed.observed !== 'object' ||
+        Array.isArray(parsed.observed)
+      ) {
+        parsed.observed = {};
+      }
+      parsed.observed[relPath] = { generation, hash, truncated: !!truncated };
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
   } catch {
     return false;
   }
@@ -434,7 +544,208 @@ export function wasObservedTruncated(hypoDir, sessionId, relPath) {
   return entry.truncated !== false;
 }
 
-// The four whole-file overwrite targets are prose-and-table markdown documents, and
+// ── applied set ──────────────────────────────────────────────────────────────
+//
+// `targets` moves on TWO kinds of legitimate write: crystallize's own overwrite
+// (invariant 2, `advanceBase`) and a direct hand edit through the session's own
+// Write/Edit tool (`advanceBaseForWrite`, wired from hypo-auto-stage.mjs). Both
+// are correct for the guard's original question, "did somebody ELSE change this
+// since I last looked": a hand edit is this session's own work, not a foreign
+// write, and must not park a close that folds it in.
+//
+// But the two are NOT the same fact, and `targets` alone cannot tell them
+// apart after the fact: once a hand edit advances `targets[relPath]` to match
+// its own new bytes, a stale close-apply payload from BEFORE that edit reads
+// disk-equals-base and rewrites over the edit with no record it ever
+// existed: the payload never touched the edit, and the edit was never
+// re-checked against it. `applied` is the narrower, second fact this closes:
+// not "what did any write show as the target's provenance", but "what did
+// THIS OVERWRITE CALL itself last put down for this key, this session": a
+// value only `recordAppliedHash` ever sets, so a hand edit through any other
+// path leaves it exactly where the last successful apply left it. When disk no
+// longer matches it, something moved the target after that apply without
+// going through it again, and the next apply of the same (or same-shaped)
+// payload must not silently bury that move.
+//
+// One entry per path, unconditionally overwritten by the next apply: there is
+// no generation to expire here, only ever "what did I last apply", so the
+// newest apply is always the only one that matters.
+
+/**
+ * Record that THIS session's own overwrite() just wrote `hash` for `relPath`.
+ * Scoped by tracked-ness like `advanceBaseForWrite`/`recordObserved`: a no-op
+ * for a key outside `targets`, so this can never mint a new guarded target.
+ *
+ * @returns {boolean} true when base.json was updated
+ */
+export function recordAppliedHash(hypoDir, sessionId, relPath, hash) {
+  if (!sessionId) return false;
+  const path = basePath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
+      if (typeof hash !== 'string') return false;
+      if (
+        !parsed.appliedHashes ||
+        typeof parsed.appliedHashes !== 'object' ||
+        Array.isArray(parsed.appliedHashes)
+      ) {
+        parsed.appliedHashes = {};
+      }
+      parsed.appliedHashes[relPath] = hash;
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clear THIS session's recorded applied-hash for `relPath`, without touching
+ * `targets`. For a writer that legitimately moves `targets[relPath]` (via
+ * `advanceBase`) but has no "applied by an overwrite() call" fact of its own to
+ * record.
+ *
+ * **No production caller right now.** The only one was
+ * `hooks/hypo-hot-rebuild.mjs`'s canonical rebuild of the root `hot.md`, and
+ * that file left `overwriteTargets` when it became a hook-generated projection,
+ * taking the whole base-vs-rebuild contention with it. Kept, with its unit
+ * coverage, for the next generated-file target that does get snapshotted; the
+ * scenario below is what it is for. Left stale, such a rebuild's `advanceBase`
+ * moves `targets`
+ * to the rebuilt bytes while `appliedHashes` still names whatever crystallize
+ * last applied; a retry of that same stale close payload then reads disk (the
+ * rebuilt bytes) as diverged from `appliedHash`, and blocker 2's "any drift
+ * from appliedHash parks" guard (`overwriteConflictReason`) mistakes the
+ * hook's own routine rebuild for a hand edit and parks it. Clearing removes the
+ * stale fact instead of leaving it to misfire: a retry after this sees no
+ * `appliedHash` for the target at all, and falls back to the plain base-vs-disk
+ * compare, same as a target crystallize has never applied to this session.
+ *
+ * The cost this accepts: a stale close payload that WOULD have been caught by
+ * the applied-hash guard can now overwrite the rebuild's canonical bytes
+ * outright, same as it could before blocker 2 existed. Rebuilt content is
+ * regenerated on the next Stop hook regardless, so this only trades one park
+ * for a page that self-heals a run later, not a real loss.
+ *
+ * @returns {boolean} true when base.json was updated
+ */
+export function clearAppliedHash(hypoDir, sessionId, relPath) {
+  if (!sessionId) return false;
+  const path = basePath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      if (
+        !parsed.appliedHashes ||
+        typeof parsed.appliedHashes !== 'object' ||
+        Array.isArray(parsed.appliedHashes) ||
+        !Object.prototype.hasOwnProperty.call(parsed.appliedHashes, relPath)
+      ) {
+        return false; // nothing recorded for this target: a no-op, not a failure
+      }
+      delete parsed.appliedHashes[relPath];
+      try {
+        atomicWrite(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `advanceBase` and `recordAppliedHash`, done as ONE read-modify-write instead
+ * of two. crystallize's own overwrite() used to call them back to back: if the
+ * first write landed and the second then failed (disk full, a permissions
+ * change mid-session, any `atomicWrite` failure), `targets[relPath]` had
+ * already moved to the new bytes while `appliedHashes[relPath]` silently kept
+ * its OLD value (the exact partial state `overwriteConflictReason`'s
+ * `appliedHash` check exists to catch, except now self-inflicted): the next
+ * apply would read disk-equals-base (base moved), see a stale `appliedHash`
+ * that does not match either, and park a WRITE that should have gone through,
+ * or (the direction review r4-w4 major 2 flagged) silently clear a
+ * genuinely stale reapply's park because the failed record made `appliedHash`
+ * read as if this call had never run at all. A `false` return here leaves
+ * BOTH fields exactly where they were (the single `atomicWrite` either lands
+ * whole or not at all): base does not move, so the next look sees the same
+ * `base-mismatch`/`base-hash-target-missing` fail-safe a foreign write would
+ * get, never a silent clean read. This is the only caller-visible difference
+ * from calling `advanceBase` then `recordAppliedHash` separately: a failure
+ * here now costs the base advance too, on purpose, because "recorded the
+ * write but forgot who wrote it" is worse than "didn't record it at all".
+ *
+ * Not a replacement for either function: `advanceBase` alone is the right call
+ * for a writer that moves a tracked target but has no "applied by THIS
+ * overwrite call" fact to record and must not manufacture one. Its last such
+ * caller was hypo-hot-rebuild.mjs, which stopped touching the base when the
+ * root `hot.md` left `overwriteTargets`.
+ *
+ * @param {{ write?: (path: string, content: string) => void }} [testHooks]
+ *   `write` is test-only: it stands in for `atomicWrite`, so a test can let the
+ *   first save land and fail a second one. A regression back to two saves then
+ *   shows up as a moved base with a stale applied hash. Production callers
+ *   never pass this.
+ * @returns {boolean} true when base.json was updated (both fields together)
+ */
+export function advanceBaseAndRecordApplied(hypoDir, sessionId, relPath, hash, testHooks) {
+  const write = testHooks?.write ?? atomicWrite;
+  if (!sessionId) return false;
+  const path = basePath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const parsed = readBaseFile(hypoDir, sessionId);
+      if (!parsed) return false;
+      if (typeof hash !== 'string') return false;
+      parsed.targets[relPath] = hash;
+      if (
+        !parsed.appliedHashes ||
+        typeof parsed.appliedHashes !== 'object' ||
+        Array.isArray(parsed.appliedHashes)
+      ) {
+        parsed.appliedHashes = {};
+      }
+      parsed.appliedHashes[relPath] = hash;
+      try {
+        write(path, JSON.stringify(parsed, null, 2));
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The hash THIS session's own overwrite() last wrote for `relPath`, or null
+ * when it never has (no snapshot, no session, or no recorded entry).
+ *
+ * @returns {string|null}
+ */
+export function readAppliedHash(hypoDir, sessionId, relPath) {
+  if (!sessionId) return null;
+  const parsed = readBaseFile(hypoDir, sessionId);
+  if (!parsed) return null;
+  const applied = parsed.appliedHashes;
+  if (!applied || typeof applied !== 'object' || Array.isArray(applied)) return null;
+  const hash = applied[relPath];
+  return typeof hash === 'string' && hash ? hash : null;
+}
+
+// The whole-file overwrite targets are prose-and-table markdown documents, and
 // a base-mismatch on one of them always parks. Five predicates lived here that tried
 // to skip the park when a payload "provably" lost nothing, and four rounds of review
 // broke all five against the real vault. The last one accepted an insertion between a
@@ -443,18 +754,26 @@ export function wasObservedTruncated(hypoDir, sessionId, relPath) {
 // from block context that begins far above the line under judgement, and a hook that
 // may use Node built-ins only is not the place to own a block parser.
 //
-// The pointer table this was built for should stop being a shared whole-file
-// overwrite target and become a locally generated projection of the per-project files
-// that already own those facts. Then two machines never contend over it, and nothing
-// here needs to prove anything.
+// The pointer table those predicates were built for is gone from this list, which
+// is the fix they were reaching for: the root `hot.md` is now a projection the
+// SessionStart and Stop hooks regenerate from `projects/*/hot.md`, not a shared
+// whole-file overwrite a close composes by hand. Two machines never contend over
+// it, and nothing here needs to prove anything about it.
 
 /**
- * The four overwrite targets crystallize replaces wholesale. `project` may be
+ * The overwrite targets crystallize replaces wholesale. `project` may be
  * null when cwd resolves to no project; the two project-scoped paths are then
  * omitted and close falls back to proposal for them.
+ *
+ * The root `hot.md` is deliberately NOT here. Snapshotting it made the hooks'
+ * own regeneration look like a foreign edit, so a close parked a `base-mismatch`
+ * on a file no human had touched. Off the list, there is no base for the guard
+ * to compare and no park to false-raise; the projection self-heals on the next
+ * Stop hook regardless. Do not add it back without first taking the regeneration
+ * out of the hooks.
  */
 export function overwriteTargets(project) {
-  const targets = ['hot.md', join('pages', 'open-questions.md')];
+  const targets = [join('pages', 'open-questions.md')];
   if (project) {
     targets.unshift(join('projects', project, 'session-state.md'));
     targets.unshift(join('projects', project, 'hot.md'));