hypomnema 1.8.2 → 1.9.0

package/hooks/hypo-session-start.mjs

@@ -8,6 +8,7 @@
  */
 
 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';
@@ -39,6 +40,12 @@ import {
   readVisibilityScope,
   pkgRootDriftStatus,
   PKG_ROOT,
+  withFileLock,
+  vaultCommitLockTarget,
+  claimAndWriteRootHotProjection,
+  recordTouchedPaths,
+  consumeRootHotHealthNotice,
+  rootHotBackupRecoveryNotice,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -52,6 +59,8 @@ import {
   computeSiblingNotice,
   siblingAlreadyNotified,
   markSiblingNotified,
+  classifyInstall,
+  parseSemver,
   pkgRootDriftAlreadyNotified,
   markPkgRootDriftNotified,
   clearPkgRootDriftNotified,
@@ -67,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
@@ -237,15 +246,176 @@ function buildSiblingNotice() {
   }
 }
 
+// Full path to the file init/upgrade own writing (hypo-shared.mjs's
+// readCachedPkgRoot reads it but does not export the path). Self-heal below
+// reads and rewrites it directly rather than adding a write path into
+// hypo-shared.mjs, which currently owns only the READ side of this file.
+const HYPO_PKG_JSON_PATH = join(homedir(), '.claude', 'hypo-pkg.json');
+
+// ── self-heal lock ───────────────────────────────────────────────────────────
+// Two sessions can self-locate to two DIFFERENT install roots at once (a dual
+// install, or one upgrade mid-flight while another session already started)
+// and both hit this same homedir()-keyed hypo-pkg.json. Reading it once,
+// comparing, then writing let whichever session finished SECOND clobber
+// whatever the first had just written, even when its own incoming version
+// was itself newer than the file's ORIGINAL value (Codex 3rd-round review,
+// 2026-09-11: reproduced by running a 1.8.2 and a 1.8.1 install against the
+// same HOME; both read the pre-existing 1.0.0, both judged themselves an
+// improvement over it, and whichever wrote last won regardless of which
+// incoming version was actually higher).
+//
+// This used to hand-roll its own `wx` lockfile (write-then-fill), which a
+// Codex 3rd-round review caught publishing an empty lock before the pid was
+// written: a holder preempted inside that window is indistinguishable from a
+// pid-less legacy lock, so a second writer steals it and both run the
+// critical section, which is the exact bug a liveness check is supposed to
+// close. `withFileLock` (below, from hypo-shared.mjs) already exists in this
+// repo, and its own docstring names that same failure mode as the reason it
+// stages the pid into a private sibling first and `linkSync`s it into place
+// atomically. Reuse it instead of repeating the mistake it was written to
+// avoid. `timeoutMs: 150` keeps the bounded, best-effort wait this hook
+// always had (long enough for a sibling session's heal, a handful of sync fs
+// calls, to finish and release; short enough that SessionStart itself never
+// stalls noticeably even under contention); `staleMs: 30000` keeps the same
+// crashed-holder cutoff the old lock used.
+//
+// withFileLock throws ELOCKTIMEOUT when it cannot acquire in time, never a
+// bare Error, so selfHealPkgRoot's caller can tell "lock contention" apart
+// from "fn() itself failed". Either way this hook must fail OPEN: a
+// SessionStart hook must never block or crash a session over a lock it
+// couldn't get, so both outcomes collapse to the caller's `{ healed: false }`
+// via the try/catch already wrapping the read-compare-write below.
+//
+// Known residue in withFileLock itself, inherited here rather than
+// re-solved: a microscopic stat-then-unlink TOCTOU on the stale-steal path
+// (a fresh holder can grab the path in that gap and have its lock removed by
+// the stealer, bounded by staleMs being far above a normal close), a
+// local-filesystem-only guarantee (no network FS atomicity), and a PID-reuse
+// window where a live process happens to reuse a crashed holder's pid and
+// gets treated as the still-alive original (an availability loss, the lock
+// is never stolen from it, not a correctness bug, since two writers still
+// never enter the critical section together).
+
+/**
+ * Self-heal `pkgRoot`/`pkgVersion` in `hypo-pkg.json` in place, once a session
+ * has already detected they disagree with the code's own self-location
+ * (`status`, from pkgRootDriftStatus()). Until now the user's only remaining
+ * job was copying those two values into the file by hand; this does that copy
+ * for them.
+ *
+ * Preserves every other key untouched (`schemaVersion`, `extensions`,
+ * `commands`, ...): this file is shared with init/upgrade's own writes, so a
+ * narrower op than "read the whole object, patch two keys, write the whole
+ * object back" would silently drop state another lane depends on. Mirrors
+ * scripts/lib/pkg-json.mjs's writeDualSkipProvenance in spirit, but cannot
+ * import it — hooks never reach into scripts/.
+ *
+ * Fails closed to `{ healed: false }` on anything short of a verified,
+ * complete write: a lock that could not be acquired (timeout or a genuine
+ * fs error from `withFileLock`), an unreadable/corrupt existing file, a
+ * non-object parse result, no resolvable-and-parseable version at the new
+ * root, a DOWNGRADE (below), or the write itself throwing. The caller must
+ * fall back to the manual `/hypo:upgrade` guidance rather than claim a fix
+ * that never landed.
+ *
+ * Concurrency: the whole read-compare-write runs inside `withFileLock`
+ * (hypo-shared.mjs), which re-reads `hypo-pkg.json` AFTER acquiring the
+ * lock, not before, since a pre-lock snapshot is exactly what let two
+ * concurrent installs race. Losing the lock (ELOCKTIMEOUT, or any other
+ * throw from `withFileLock` or from `fn` itself) is caught by the outer
+ * try/catch and treated as fail-open: this session simply skips the heal,
+ * the same outcome as any other precondition miss below.
+ *
+ * The lock's reach is narrower than the sentence above about sharing this
+ * file with init/upgrade might suggest: it serializes SessionStart heals
+ * against each other, and nothing else. `writePkgJsonAtomic` (what init,
+ * upgrade and writeDualSkipProvenance go through) does not take it, so an
+ * `upgrade --apply` running while another session starts is still a lost
+ * update. The damage is bounded rather than absent: heal refuses a
+ * downgrade, so whichever write lands last leaves `pkgVersion` at the same
+ * value or higher. That bound is the whole argument for leaving it, and it
+ * dies the moment a heal path is allowed to lower the version.
+ *
+ * Downgrade guard: a dual install (e.g. a plugin-scope cache at 1.8.2 and a
+ * project-scope cache at 1.8.1, both reading the SAME `hypo-pkg.json` because
+ * that path is keyed on `homedir()`, not on scope) means a session that
+ * happens to self-locate to the OLDER sibling would otherwise overwrite this
+ * file's `pkgVersion` with a lower number — the one baseline
+ * `scripts/upgrade.mjs`'s downgrade guard and `hooks/version-check.mjs`'s
+ * `computeSiblingNotice` both compare against. `classifyInstall` is the same
+ * judgment those two already trust, but this only blocks the `'downgrade'`
+ * verdict: a comparison that resolves and comes out lower. On `'downgrade'`,
+ * this returns `{ healed: false }` before touching the file, so the normal
+ * failure fallback below fires the original manual-fix guidance instead of
+ * quietly recording the sibling's older version as truth.
+ *
+ * Direction matters for the `'unknown'` verdict (one side's semver failed to
+ * parse), which is why the INCOMING version is checked with `parseSemver`
+ * up front rather than folded into the same `'unknown'` escape hatch as an
+ * unparseable EXISTING value. An unparseable incoming version must never
+ * heal: that would overwrite a good `pkgVersion` with garbage read from a
+ * corrupt `package.json` (Codex 3rd-round review, 2026-09-11: reproduced with
+ * `package.json.version: "not-semver"` against an existing `1.8.2`, which
+ * used to heal to `"not-semver"`). An unparseable EXISTING value with a
+ * valid incoming one is the opposite case, a good value replacing a
+ * corrupted one, and is still allowed through by `classifyInstall`'s
+ * `'unknown'` verdict: there is no valid comparison to protect against
+ * there, and refusing it would leave a broken value in place forever with no
+ * path back to a good one.
+ */
+function selfHealPkgRoot(status) {
+  try {
+    return withFileLock(
+      HYPO_PKG_JSON_PATH,
+      () => {
+        const meta = JSON.parse(readFileSync(HYPO_PKG_JSON_PATH, 'utf-8'));
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return { healed: false };
+        const newVersion = readInstalledVersion(status.self);
+        if (!newVersion || !parseSemver(newVersion)) return { healed: false };
+        const oldVersion = typeof meta.pkgVersion === 'string' ? meta.pkgVersion : null;
+        const incoming = { pkgRoot: status.self, version: newVersion };
+        const active = { pkgRoot: meta.pkgRoot, version: oldVersion };
+
+        if (classifyInstall(incoming, active) === 'downgrade') return { healed: false };
+        const updated = { ...meta, pkgRoot: status.self, pkgVersion: newVersion };
+        // 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.
+        // 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 },
+    );
+  } catch {
+    // Fail open: a lock timeout (ELOCKTIMEOUT) or any other throw from
+    // withFileLock/fn must not block or crash SessionStart. The caller
+    // treats this exactly like any other heal precondition miss.
+    return { healed: false };
+  }
+}
+
 /**
  * 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.
+ * disagrees with the cached hypo-pkg.json — but silent self-correction used
+ * to leave the FILE itself stale forever, with nothing but a "please copy
+ * these two values in yourself" notice to show for it. This now does that
+ * copy itself (selfHealPkgRoot above), on the spot, in the same session that
+ * detected the drift.
+ *
+ * Notify-once cache: a successful heal marks the (cached → self-location)
+ * pair notified, but next session's pkgRootDriftStatus() reads back 'match'
+ * from the now-fixed file regardless and clears it on its own — the mark here
+ * only prevents a duplicate "fixed" line within a session that re-checks
+ * drift more than once. A FAILED heal must NOT mark the pair: marking would
+ * suppress the only guidance the user has (the manual `/hypo:upgrade` line)
+ * for a drift that never actually got fixed, on every later session that
+ * hits the same stale pair.
  *
  * Tri-state (pkgRootDriftStatus): 'match' CLEARS any earlier mark (checked
  * FIRST, unconditionally — even under opt-out, so a drift that resolves while
@@ -253,8 +423,9 @@ function buildSiblingNotice() {
  * 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.
+ * banner (or attempt a heal), and opt-out is checked there so an opted-out
+ * session never writes a fix — or marks a pair notified — it never actually
+ * showed.
  */
 function buildPkgRootDriftNotice() {
   try {
@@ -269,7 +440,24 @@ function buildPkgRootDriftNotice() {
     const key = `${status.cached || '(none)'}->${status.self}`;
     const cache = readCache(cachePath);
     if (pkgRootDriftAlreadyNotified(cache, key)) return '';
-    markPkgRootDriftNotified(cachePath, key);
+
+    const heal = selfHealPkgRoot(status);
+    if (heal.healed) {
+      markPkgRootDriftNotified(cachePath, key);
+      return (
+        `[Hypomnema] Package metadata drift fixed: hypo-pkg.json pointed at ` +
+        `\`${status.cached || '(none)'}\`` +
+        `${heal.oldVersion ? ` (version ${heal.oldVersion})` : ''}, now synced to ` +
+        `\`${status.self}\` (version ${heal.newVersion}).\n` +
+        `  This was corrected automatically for this session — no action needed.`
+      );
+    }
+
+    // Heal did not land (unreadable/corrupt hypo-pkg.json, no resolvable
+    // version at the new root, or the write itself failed). Do NOT mark this
+    // pair notified here — see the docstring above — and fall back to the
+    // original manual-fix guidance.
+    //
     // status.cached is null both for a genuinely fresh install (never ran
     // /hypo:init) AND for the channel-judgment-failure guard (init/upgrade
     // positively decided to leave pkgRoot unset; see scripts/init.mjs's
@@ -287,7 +475,7 @@ function buildPkgRootDriftNotice() {
       `\`${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${recoveryLine}`
+      `heads-up, not a blocker (the automatic fix did not take — see below).\n${recoveryLine}`
     );
   } catch {
     return '';
@@ -471,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 '';
   }
@@ -721,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();
@@ -788,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
@@ -796,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)
@@ -823,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);
@@ -969,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,