hypomnema 1.8.4 → 1.9.0

package/hooks/hypo-session-start.mjs

@@ -7,7 +7,8 @@
  *   MISS → inject global hot.md pointer only (no fan-out to all projects)
  */
 
-import { readFileSync, writeFileSync, existsSync, realpathSync, renameSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
+import { atomicWrite } from './atomic-write.mjs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -40,6 +41,11 @@ import {
   pkgRootDriftStatus,
   PKG_ROOT,
   withFileLock,
+  vaultCommitLockTarget,
+  claimAndWriteRootHotProjection,
+  recordTouchedPaths,
+  consumeRootHotHealthNotice,
+  rootHotBackupRecoveryNotice,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -70,7 +76,7 @@ import {
   recordObserved,
   hashContent,
 } from './base-store.mjs';
-import { listProposals } from './proposal-store.mjs';
+import { listProposalsChecked } from './proposal-store.mjs';
 
 // Privacy guard: refuse to read+inject .hypoignore-matched
 // wiki files into additionalContext. Without this, a user who lists
@@ -375,13 +381,12 @@ function selfHealPkgRoot(status) {
         // temp + rename in the SAME directory: a crash mid-write leaves only a
         // throwaway temp file behind, never a torn hypo-pkg.json that the next
         // session's every hook read of this file would then choke on.
-        const dir = dirname(HYPO_PKG_JSON_PATH);
-        const tmp = join(
-          dir,
-          `.hypo-pkg.json.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`,
-        );
-        writeFileSync(tmp, `${JSON.stringify(updated, null, 2)}\n`);
-        renameSync(tmp, HYPO_PKG_JSON_PATH);
+        // Shared writer rather than a local temp+rename: this one had no
+        // cleanup, so a failed rename left its temp behind for good. The temp
+        // name loses its leading dot in the trade, so a leaked one would now be
+        // visible in a directory the user reads; that is the point, since the
+        // shared writer is the one that does not leak.
+        atomicWrite(HYPO_PKG_JSON_PATH, `${JSON.stringify(updated, null, 2)}\n`);
         return { healed: true, oldVersion, newVersion };
       },
       { timeoutMs: 150, staleMs: 30_000, pollMs: 20 },
@@ -654,15 +659,30 @@ function syncStateNotice(pullOk) {
  * exactly like syncStateNotice: the line joins the `notices` array (→
  * additionalContext) and is also written to stderr, so both the model and the
  * user's transcript see it. NOT a systemMessage banner (that channel is
- * reserved for the update/sibling notices). Pure read (listProposals never
- * mutates); best-effort so a store read failure never breaks SessionStart. '' when
- * there are no pending proposals, so nothing surfaces on the empty path.
+ * reserved for the update/sibling notices). Pure read (listProposalsChecked
+ * never mutates); best-effort so a store read failure never breaks
+ * SessionStart. '' when there are no pending proposals AND nothing is wrong
+ * with the store, so nothing surfaces on the ordinary empty path.
+ *
+ * Uses listProposalsChecked rather than the plain listProposals this used to
+ * call: a store that could not be listed at all (`ok: false`, permissions or
+ * a file sitting where the directory should be) and a store with an
+ * unparseable `.json` candidate both used to look identical to zero here,
+ * silently, at the start of every session. Both get a short clause appended
+ * to the SAME line rather than a line of their own, so a clean vault's
+ * prompt budget does not grow by a byte.
  */
 function pendingProposalNotice() {
   try {
-    const n = listProposals(HYPO_DIR).length;
-    if (n === 0) return '';
-    return `[WIKI: 대기 proposal ${n}건 (검토: hypomnema proposal list)]`;
+    const inventory = listProposalsChecked(HYPO_DIR);
+    if (!inventory.ok) return '[WIKI: 파킹 proposal 측정 불가 (hypomnema doctor 확인)]';
+    const n = inventory.proposals.length;
+    const u = inventory.unreadable.length;
+    if (n === 0 && u === 0) return '';
+    const parts = [];
+    if (n > 0) parts.push(`대기 proposal ${n}건 (검토: hypomnema proposal list)`);
+    if (u > 0) parts.push(`안 읽히는 후보 ${u}건 (hypomnema doctor 확인)`);
+    return `[WIKI: ${parts.join(', ')}]`;
   } catch {
     return '';
   }
@@ -904,7 +924,32 @@ process.stdin.on('end', () => {
       data = JSON.parse(raw);
     } catch {}
 
-    const pullOk = gitPull(HYPO_DIR);
+    // BLOCKER fix: serialized against every other writer of this vault
+    // (hypo-auto-commit.mjs's stage+commit+sync, crystallize.mjs's apply, and
+    // writeRootHotProjection below) on the SAME lock. A fast-forward pull
+    // rewrites hot.md as surely as the projection writer does, so locking the
+    // writer alone would just move the unguarded overwrite onto this line.
+    // Not reentrant: this hold is released before the projection call below
+    // takes the same lock for itself, and nothing between them holds it.
+    //
+    // A lock timeout leaves pullOk false, which is the same state a failed
+    // pull produces: the sync-state notice stays unresolved for one more
+    // session rather than being cleared on a pull that never ran.
+    //
+    // The `.git` check is gitPull's own precondition, hoisted out so the lock
+    // is never taken for a call that cannot pull: withFileLock creates the
+    // lock's parent directory, which on an install with no vault would mint
+    // `.cache/` under a wiki root that does not exist.
+    let pullOk = false;
+    if (existsSync(join(HYPO_DIR, '.git'))) {
+      try {
+        pullOk = withFileLock(vaultCommitLockTarget(HYPO_DIR), () => gitPull(HYPO_DIR), {
+          timeoutMs: Number(process.env.HYPO_VAULT_LOCK_TIMEOUT_MS) || 5000,
+        });
+      } catch {
+        pullOk = false;
+      }
+    }
     const syncLine = syncStateNotice(pullOk);
     const proposalLine = pendingProposalNotice();
     const growthLine = readLastGrowthLine();
@@ -971,6 +1016,197 @@ process.stdin.on('end', () => {
       process.stderr.write(`\n\x1b[33m${foreignNotice}\x1b[0m\n`);
     }
 
+    // Root hot.md projection. Must run AFTER gitPull (so it
+    // reflects the merged tree) and BEFORE snapshotBase below (so this
+    // session's base for 'hot.md' is the freshly generated bytes, not
+    // whatever was on disk before this write). Also deliberately AFTER
+    // foreignUncommittedNotice above: that check reads `git status` on the
+    // wiki tree, and this session's OWN regeneration of hot.md is not a
+    // foreign or unattributed change: running the write first would make the
+    // projection's own necessary write show up in that scan and misreport as
+    // one. resolveActiveProject, closeCandidateSlugs, and the HIT/MISS
+    // injection later in this hook all read hot.md, so the write still has to
+    // land before any of those.
+    // recordTouchedPaths here is the ONLY thing that gets this write into a
+    // scoped hypo-auto-commit at Stop. Without it: SessionStart writes fresh
+    // bytes, Stop's own rebuild sees disk already equals the projection
+    // (writeRootHotProjection's no-op branch) and records nothing touched, and
+    // hypo-auto-commit only ever commits its touched-paths set, so the write
+    // this hook just made would never be staged or committed by ANY path, and
+    // would sit as an unattributable dirty file (closeFileTargetsGlobal scopes
+    // hot.md as close-owned; classifyForeignOnlyDirty cannot demote it to
+    // foreign) blocking both the close gate and PreCompact. TODO(wave 3): this
+    // whole call disappears the moment hot.md comes out of overwriteTargets /
+    // the commit path, since a projection target no longer needs a commit.
+    //
+    // The touched-paths record is claimed BEFORE the write, not after: it is
+    // itself best-effort (a lock timeout can fail it), and recording it after
+    // the fact means a failure there leaves a real disk write with nothing in
+    // any session's touched-paths set, the exact orphan this comment already
+    // described, just moved from "Stop's rebuild is a no-op" to "the record
+    // call itself failed." Claiming it first and skipping the write on a
+    // failed claim means hot.md is never rewritten without something able to
+    // account for that rewrite at close time.
+    //
+    // The claim and the write share one hold of the vault lock
+    // (claimAndWriteRootHotProjection). Claimed first and locked second, a
+    // Stop for the same session_id could take the lock in between, retire
+    // the still-unwritten claim, and leave the write that followed with no
+    // claim at all.
+    if (existsSync(HYPO_DIR)) {
+      // A missing session_id reads as "not claimed" here (claimProjectionWrite
+      // underneath), unlike every other best-effort accumulate call, or this
+      // write proceeds with nothing able to ever bring it into a commit.
+      let outcome;
+      let writeError = null;
+      try {
+        // n1 fix: session_id goes along so this session's own digest lands in
+        // ITS OWN receipt, not just the shared global ownership record (see
+        // writeRootHotProjection's doc comment).
+        outcome = claimAndWriteRootHotProjection(HYPO_DIR, data.session_id);
+      } catch (err) {
+        writeError = err;
+      }
+      if (writeError) {
+        // BLOCKER fix: writeRootHotProjection now throws instead of
+        // silently treating an unreadable existing hot.md as absent. The
+        // claim this call added was already dropped inside the lock (see
+        // claimAndWriteRootHotProjection), so no stale 'hot.md' claim is
+        // left to sweep in whatever another session or a person writes next.
+        // catch-message-accuracy fix (r5-w1.md): the write can throw from
+        // several different steps (reading the existing file, writing the
+        // migration backup, updating .gitignore, or the final atomic write
+        // itself), not only a read failure: wording this as "읽을 수 없어"
+        // (could not read) misnamed a disk-full or backup-write failure as
+        // something it was not. What stays true regardless of which step
+        // failed is that the atomic write never ran, so the old file is
+        // untouched.
+        const err = writeError;
+        const msg = `루트 hot.md 갱신에 실패해 이전 파일을 그대로 두었습니다: ${err?.message ?? String(err)}`;
+        notices.push(msg);
+        noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+        outExtra = {
+          ...outExtra,
+          systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+        };
+        process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+      } else if (outcome.claimFailed) {
+        const msg =
+          '루트 hot.md 갱신을 건너뛰었습니다: 이번 세션의 커밋 범위에 기록하지 못해 갱신 후 미커밋 파일로 남을 수 있었습니다.';
+        notices.push(msg);
+        noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+        outExtra = {
+          ...outExtra,
+          systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+        };
+        process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+      } else {
+        const { result } = outcome;
+        if (result.lockTimeout) {
+          // BLOCKER fix, the other half: the projection writer holds the
+          // vault lock, so a vault busy with another session's commit can
+          // leave this session on the previous pointer table. Say so instead
+          // of starting the session on a stale table with no explanation.
+          // No claim to drop: it is taken inside the same lock, so a lock
+          // timeout means this run never claimed anything, and a resumed
+          // session_id's earlier, still-unresolved 'hot.md' claim is left
+          // exactly as it was.
+          const msg =
+            '루트 hot.md 를 갱신하지 못했습니다: 다른 세션이 이 저장소를 쓰는 중이라 잠금을 얻지 못했습니다. 이번 세션은 이전 포인터 표를 그대로 읽습니다 (다음 세션 시작이나 종료 때 다시 시도합니다).';
+          notices.push(msg);
+          noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+          outExtra = {
+            ...outExtra,
+            systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+          };
+          process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+        } else if (result.scanError) {
+          const msg =
+            '루트 hot.md 갱신 실패: projects/ 디렉터리를 읽을 수 없어 이전 파일을 그대로 두었습니다.' +
+            ` 권한과 경로를 확인하고(\`ls -ld ${join(HYPO_DIR, 'projects')}\`), 고치면 다음 세션 시작이나 종료 때 자동으로 다시 시도합니다.`;
+          notices.push(msg);
+          noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+          outExtra = {
+            ...outExtra,
+            systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+          };
+          process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+        } else if (result.warnings.length > 0) {
+          // major-1/3: a per-project read failure no longer disappears
+          // silently: it kept its row (blank date) in the table already
+          // written above, but the reason must still reach a human.
+          const msg =
+            `루트 hot.md 갱신 중 일부 프로젝트를 읽지 못했습니다:\n${result.warnings.join('\n')}\n` +
+            '해당 파일의 권한과 경로를 확인하면 다음 세션 시작이나 종료 때 자동으로 다시 읽습니다.';
+          notices.push(msg);
+          noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+          outExtra = {
+            ...outExtra,
+            systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+          };
+          process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+        }
+        if (result.gitignoreUpdated) {
+          // Best-effort: the gitignore change itself already landed on
+          // disk (writeRootHotProjection would have thrown otherwise); a
+          // failure to also claim it only risks THIS one infra file
+          // showing up as an unattributed dirty file at close, not the
+          // backup it protects (which is gitignored either way).
+          const gClaimed = recordTouchedPaths(HYPO_DIR, data.session_id, ['.gitignore']);
+          if (!gClaimed) {
+            process.stderr.write(
+              '[hypo-session-start] .gitignore 갱신(백업 유출 방지 패턴)을 커밋 범위에 기록하지 못했습니다\n',
+            );
+          }
+        }
+        if (result.backedUp && result.backupPath) {
+          // MAJOR fix: the backup itself was never in question (it lands
+          // on disk and is gitignored either way), only whether a human
+          // ever learns it exists. Before this, `backedUp`/`backupPath`
+          // reached neither `notices` nor `systemMessage`: the backup file
+          // is gitignored, so it does not even show up in `git status`, and
+          // a person who had just hand-edited root hot.md would see their
+          // edit silently replaced with no trace of where it went. Naming
+          // only the file (basename), not its full path: the vault root is
+          // already implied by the session, and nothing else here leaks a
+          // full filesystem path into a notice. This branch should be rare
+          // once rootHot leaves the close payload/overwrite targets: with
+          // no scripted writer left that targets this file, a backup only
+          // happens when a person edits it by hand, so this notice does
+          // not become noise on every session.
+          // Naming the file is not a recovery path on its own: copying the
+          // backup back onto root hot.md just gets it replaced again on the
+          // next rebuild. rootHotBackupRecoveryNotice (hooks/hypo-shared.mjs)
+          // is the one sentence that says what actually recovers the
+          // content, shared with the Stop-hook rebuild and project-create so
+          // the three writers cannot drift into different wordings.
+          const msg = rootHotBackupRecoveryNotice(result.backupPath);
+          notices.push(msg);
+          noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+          outExtra = {
+            ...outExtra,
+            systemMessage: [outExtra.systemMessage, msg].filter(Boolean).join('\n\n'),
+          };
+          process.stderr.write(`\n\x1b[33m${msg}\x1b[0m\n`);
+        }
+      }
+    }
+
+    // A prior Stop's rebuild may have failed invisibly (its own stdout is
+    // suppressed) and left a note for the next SessionStart to show. One-shot:
+    // consumed (and deleted) the moment it is read, so it surfaces exactly
+    // once instead of repeating on every future session.
+    const staleProjectionNotice = consumeRootHotHealthNotice(HYPO_DIR);
+    if (staleProjectionNotice) {
+      notices.push(staleProjectionNotice);
+      noticePrefix = notices.length ? `${notices.join('\n\n')}\n\n` : '';
+      outExtra = {
+        ...outExtra,
+        systemMessage: [outExtra.systemMessage, staleProjectionNotice].filter(Boolean).join('\n\n'),
+      };
+      process.stderr.write(`\n\x1b[33m${staleProjectionNotice}\x1b[0m\n`);
+    }
+
     // Observed-base snapshot for the write=proposal gate. Deliberately AFTER gitPull: the base must
     // describe the tree this session actually starts from, remote merges
     // included, or the first close would raise a proposal against content the
@@ -979,8 +1215,24 @@ process.stdin.on('end', () => {
     // alone. `data.session_id` is used raw rather than the 'default' fallback
     // above. A session with no id has no base and closes down the legacy
     // direct-write path.
+    //
+    // Only the root-only targets (hot.md, open-questions.md) are snapshotted
+    // HERE, unconditionally. They carry no .hypoignore/visibility gate of
+    // their own, so hashing them before any injection decision costs
+    // nothing a later read would have refused anyway. The current project's
+    // OWN two targets (hit.proj's hot.md / session-state.md) used to be
+    // snapshotted right here too, blind to whether the HIT branch below was
+    // about to actually show them (review r4-w4 major 3): that let a
+    // .hypoignore'd or machine-scoped-out project target mint a "clean" base
+    // from bytes this session was never shown a single line of, and for a
+    // LATE HIT (this session's cwd only resolves to a project on a later
+    // resume/compact, not its first SessionStart), that base came from
+    // whatever was on disk at that arbitrary later moment, with no relation
+    // to what injection actually revealed. Enrollment for those two moved
+    // down to right after the HIT branch's own reads decide that question
+    // (see the call there).
     if (data.session_id) {
-      snapshotBase(HYPO_DIR, data.session_id, overwriteTargets(hit ? hit.proj : null));
+      snapshotBase(HYPO_DIR, data.session_id, overwriteTargets(null));
       // Bumps the observed generation on EVERY SessionStart (first run and
       // resume/compact alike), before the injections below record into it. A
       // resume that ends up injecting nothing (ignored, scoped out, absent)
@@ -1006,6 +1258,109 @@ process.stdin.on('end', () => {
       const TODAY = new Date().toISOString().slice(0, 10);
       const hotRead = readIfNotIgnored(hit.hotPath, HOT_CHARS, ignorePatterns);
       const stateRead = readIfNotIgnored(hit.statePath, STATE_CHARS, ignorePatterns);
+      // Enroll THIS project's two overwrite targets now, right next to the
+      // reads that just decided whether this session is actually about to be
+      // shown them (review r4-w4 major 3: see the top-of-hook snapshotBase
+      // call's comment for why this moved here instead of running blind
+      // before this decision existed). A target `readIfNotIgnored` refused
+      // (.hypoignore, machine-scoped-out) but that still exists on disk is
+      // left OUT of `relPaths` on purpose: `snapshotBase` would otherwise
+      // hash it anyway (it re-reads disk itself, not these `Read`s) and mint
+      // a base from bytes this session was never shown, so the key stays
+      // 'unknown' and this session's closes keep failing safe on it, same as
+      // before late enrollment existed. A target genuinely absent on disk
+      // (no file yet) is still safe to enroll as `null` (nothing was hidden
+      // from anyone, there is simply nothing there yet), so `existsSync`
+      // lets that case through even though `readIfNotIgnored` also returns
+      // null for it.
+      //
+      // `knownHashes` (review r5-w3 blocker 1): the root-only snapshotBase
+      // call above (line ~999) always creates base.json before this HIT
+      // branch runs, so this call would otherwise ALWAYS take snapshotBase's
+      // "enroll" branch and hash `hit.hotPath`/`hit.statePath` off disk again,
+      // a SEPARATE read from `hotRead`/`stateRead` above. A writer landing in
+      // that window mints a base from bytes this session was never shown, and
+      // a later close built from `hotRead.raw`/`stateRead.raw` reads
+      // disk-equals-base and overwrites that writer's change with no park.
+      // Passing the hash of the bytes `hotRead`/`stateRead` ALREADY read pins
+      // the base to what this session was actually shown, not to whatever a
+      // second, independent read happens to find.
+      if (data.session_id) {
+        // Test-only barrier, the other half of the enroll probe below. The
+        // dump alone catches a call that drops `knownHashes`, but not one
+        // that re-reads disk here and hashes that: with nothing changing the
+        // file, the re-read and the shown bytes agree. When
+        // HYPO_TEST_ENROLL_BARRIER is a non-empty string, the hook says so on
+        // stderr and waits until that path exists (10s at most), which gives
+        // a test the gap between the reads above and the hashing below to
+        // change the file in. It only waits and reads: it writes no file,
+        // inside the vault or out, for the reason the dump comment gives.
+        const barrier = process.env.HYPO_TEST_ENROLL_BARRIER;
+        if (typeof barrier === 'string' && barrier.length > 0) {
+          process.stderr.write('[hypo-test] enroll-barrier-ready\n');
+          const deadline = Date.now() + 10000;
+          while (!existsSync(barrier) && Date.now() < deadline) {
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+          }
+        }
+        const relPaths = [];
+        const knownHashes = {};
+        const hotRelPath = join('projects', hit.proj, 'hot.md');
+        const stateRelPath = join('projects', hit.proj, 'session-state.md');
+        if (hotRead) {
+          relPaths.push(hotRelPath);
+          knownHashes[hotRelPath] = hashContent(hotRead.raw);
+        } else if (!existsSync(hit.hotPath)) {
+          relPaths.push(hotRelPath);
+          knownHashes[hotRelPath] = null; // observed-absent, not unread
+        }
+        if (stateRead) {
+          relPaths.push(stateRelPath);
+          knownHashes[stateRelPath] = hashContent(stateRead.raw);
+        } else if (!existsSync(hit.statePath)) {
+          relPaths.push(stateRelPath);
+          knownHashes[stateRelPath] = null;
+        }
+        // Test-only wiring probe (review r5-w4 blocker 1,
+        // tests/proposal-base.test.mjs). It replaced a seam that wrote
+        // `process.env.HYPO_TEST_RACE_HOT_WRITE` straight into `hit.hotPath`
+        // to fake a concurrent writer: every file under hooks/ is copied into
+        // every install, that path is a real person's project hot.md, and the
+        // guard was `!== undefined`, so an empty value truncated the file to
+        // zero bytes. Nothing here writes inside the vault any more.
+        //
+        // What is left is the half the seam was actually needed for. Whether
+        // `snapshotBase` honors a hash it is told is a property of
+        // `snapshotBase`, and a direct unit test covers it; whether THIS call
+        // site hands it the hashes of the bytes it just showed is only
+        // observable here, and dropping the argument leaves every other
+        // real-hook test green (with no writer in the gap, a fresh disk read
+        // and the shown bytes agree). So when HYPO_TEST_ENROLL_DUMP names a
+        // path, the arguments this call actually passes are written there as
+        // JSON, and a test reads them back. `args`, not the local
+        // `knownHashes`: reading the local would report the map as passed even
+        // when the call below stopped passing it, which is precisely the
+        // regression this exists to catch. An argument list of three shows up
+        // as `argc: 3` with no `knownHashes` key at all.
+        //
+        // Best-effort, like every other cache write in these hooks: a bad
+        // dump path must not take down a SessionStart.
+        const enroll = (...args) => {
+          const dumpPath = process.env.HYPO_TEST_ENROLL_DUMP;
+          if (dumpPath) {
+            try {
+              writeFileSync(
+                dumpPath,
+                JSON.stringify({ argc: args.length, relPaths: args[2], knownHashes: args[3] }),
+              );
+            } catch {
+              // ignore: the probe is diagnostics, never a precondition
+            }
+          }
+          return snapshotBase(...args);
+        };
+        if (relPaths.length) enroll(HYPO_DIR, data.session_id, relPaths, knownHashes);
+      }
       let hotContent = hotRead ? hotRead.shown : null;
       let stateContent = stateRead ? stateRead.shown : null;
       const hotMarker = staleMarkerForPath(hit.hotPath, ignorePatterns, TODAY);
@@ -1152,9 +1507,17 @@ process.stdin.on('end', () => {
     );
     // Observed-set record: the MISS branch's root hot.md injection is the one
     // place a project-less session observes anything at all. Recorded AFTER
-    // the console.log above — see the HIT branch's comment for why (fail-open
+    // the console.log above. See the HIT branch's comment for why (fail-open
     // ordering). Hashes `.raw`, not a fresh disk read, for the same reason
     // given there.
+    //
+    // This call records nothing any more. overwriteTargets() stopped returning
+    // 'hot.md' when the root pointer table became a hook-generated projection,
+    // and recordObserved only writes for keys the base snapshot is tracking, so
+    // the guard rejects this one every time. It is kept here, rather than
+    // deleted, because this file is being rewritten in another lane at the same
+    // time and a deletion would widen that merge. Delete it when the two lanes
+    // land together.
     if (data.session_id) {
       recordObserved(
         HYPO_DIR,