hypomnema 1.7.0 → 1.7.2

package/hooks/hypo-shared.mjs

@@ -17,13 +17,15 @@ import {
   readdirSync,
   realpathSync,
   openSync,
-  closeSync,
   unlinkSync,
   renameSync,
+  linkSync,
 } from 'fs';
-import { join, relative, basename, dirname } from 'path';
+import { join, relative, basename, dirname, isAbsolute } from 'path';
 import { homedir, hostname, tmpdir } from 'os';
 import { spawnSync } from 'child_process';
+import { randomBytes, createHash } from 'crypto';
+import { fileURLToPath } from 'url';
 
 const HOME = homedir();
 
@@ -94,19 +96,289 @@ export const LOG_PATH = join(HYPO_DIR, 'log.md');
 export const HOT_PATH = join(HYPO_DIR, 'hot.md');
 export const GUIDE_PATH = join(HYPO_DIR, 'hypo-guide.md');
 
-// Package root: written by init/upgrade to ~/.claude/hypo-pkg.json
-function resolvePkgRoot() {
-  const p = join(HOME, '.claude', 'hypo-pkg.json');
-  if (!existsSync(p)) return null;
+// Package root: written by init/upgrade to ~/.claude/hypo-pkg.json.
+//
+// The plugin channel is the primary distribution path, and
+// Claude Code's own plugin manager updates hooks WITHOUT ever touching
+// hypo-pkg.json — only our own init/upgrade write it. So after a plugin
+// auto-update this file can point at a stale pkgRoot indefinitely with no
+// signal to the user, and PKG_ROOT (resolved here) is what lint/feedback
+// scripts get resolved through — a hook can run at the new version while the
+// script it shells out to still runs from the old one.
+//
+// An earlier version of this cross-check queried ~/.claude/settings.json's
+// `enabledPlugins` + the plugin registry to positively attribute an active
+// install. That was wrong: Claude Code layers `enabledPlugins` across
+// user/project/local/managed settings (project overrides user), and a plugin
+// with no explicit key is enabled by default — so a single-file read of the
+// user settings can neither prove "enabled" nor "disabled". Querying it was
+// certain to misjudge some real layout.
+//
+// This code already knows the one thing that can't be wrong: where IT is
+// running from. `import.meta.url`, walked up to the nearest package.json,
+// names the actual root of the code executing right now — no
+// settings/registry guessing needed. That's `selfLocationPkgRoot()` below.
+//
+// Never throw: this runs at hook-module load time (`export const PKG_ROOT =
+// resolvePkgRoot()`), so a throw here takes the whole hook process down.
+// Every read below is try/caught and every helper fails open to null.
+
+/** Non-mutating read of the cached pointer, or null on any absence/corruption. */
+function readCachedPkgRoot() {
   try {
+    const p = join(HOME, '.claude', 'hypo-pkg.json');
+    if (!existsSync(p)) return null;
     const v = JSON.parse(readFileSync(p, 'utf-8')).pkgRoot;
     return typeof v === 'string' && v ? v : null;
   } catch {
     return null;
   }
 }
+
+// A pkgRoot is usable only as an ABSOLUTE path to a real package directory
+// whose package.json carries a version. A relative path (e.g. ".") resolves
+// against whatever cwd the reading process happens to have; a directory that
+// merely EXISTS but carries no versioned package.json is a pointer nothing
+// can actually resolve scripts through. Same contract for every source of a
+// pkgRoot value in this file — the cache included (a cached `pkgRoot: "."`
+// used to pass on directory-existence alone).
+//
+// NOT sufficient by itself for self-location (see selfLocationPkgRoot below):
+// "absolute path + a package.json with SOME version" is true of any Node
+// package anywhere on disk, including one that has nothing to do with
+// Hypomnema — e.g. `$HOME/package.json` from an unrelated project. This
+// contract answers "is this a real, resolvable directory", not "is this OUR
+// package". Callers that need the latter also require self-containment.
+//
+// Exported so scripts/doctor.mjs can apply the SAME predicate to a sidecar's
+// recorded pkgRoot that readVerifiedProvenancePkgRoot() below applies at
+// runtime — doctor used to hand-roll a thinner name+hash check that a
+// version-less "name":"hypomnema" root would pass while the runtime resolver
+// rejects it, so doctor could PASS a sidecar the runtime treats as null. The
+// import direction stays scripts/ → hooks/, never the reverse.
+export function isUsablePkgRootLocal(pkgRoot) {
+  if (typeof pkgRoot !== 'string' || !pkgRoot || !isAbsolute(pkgRoot)) return false;
+  try {
+    const v = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+// True iff `candidateRoot` actually CONTAINS the module that is running right
+// now — i.e. `<candidateRoot>/hooks/hypo-shared.mjs` is, on disk, the exact
+// same file as `ownRealPath` (this module's own realpath). This is the
+// decisive check self-location needs and isUsablePkgRootLocal alone cannot
+// give it: a versioned package.json only proves SOME package lives at
+// `candidateRoot`, not that it is the Hypomnema install this code is part of.
+// Without this, walking up from an unrelated location (a standalone-copied
+// hooks/ dir sitting under a directory that happens to have its own,
+// unrelated package.json a few levels up — e.g. `$HOME/package.json`) would
+// silently adopt that unrelated tree as PKG_ROOT, and every script path built
+// from it (`join(PKG_ROOT, 'scripts', 'lint.mjs')`, the crystallize recovery
+// command in hypo-auto-minimal-crystallize.mjs, etc.) would point at files
+// that were never shipped there.
+//
+// Both paths are realpath'd before comparing so a symlinked candidate or a
+// symlinked ancestor of the running module (macOS's /var → /private/var, a
+// symlinked plugin cache dir) still compares correctly. Fails closed (false)
+// on any read error — a candidate this can't positively confirm is never
+// adopted.
+function candidateContainsRunningModule(candidateRoot, ownRealPath) {
+  try {
+    return realpathSync(join(candidateRoot, 'hooks', 'hypo-shared.mjs')) === ownRealPath;
+  } catch {
+    return false;
+  }
+}
+
+// Walk up from the PARENT of the directory this module (hooks/hypo-shared.mjs)
+// is actually running from, looking for the nearest ancestor that is (a) a
+// usable package root AND (b) actually contains this exact running module —
+// that IS the package root of the code currently executing, regardless of
+// which channel put it there (plugin, npm, dev checkout).
+//
+// Plugin mode runs hooks straight out of the plugin's own cache directory
+// (`${CLAUDE_PLUGIN_ROOT}/hooks/...`), so this resolves directly to whatever
+// the plugin loader most recently updated — exactly the channel that can
+// silently drift ahead of hypo-pkg.json. A manual/npm install COPIES hooks
+// standalone into ~/.claude/hooks/ with no package.json alongside (the "hooks
+// import only Node built-ins, nothing outside the hooks dir" contract), so
+// this correctly finds nothing self-containing there and resolvePkgRoot()
+// falls through to the cache — which IS authoritative for that channel, since
+// our own init/upgrade own writing it. And even if SOME unrelated ancestor
+// happens to carry its own versioned package.json (a plain "usable" root),
+// candidateContainsRunningModule rejects it: that ancestor's own hooks/
+// subdirectory (if it even has one) is not this file.
+//
+// Bounded walk: up to 6 candidate ancestors above hooksDir's own parent (the
+// ordinary root sits at the very first one; a few extra levels tolerate an
+// unusual nesting depth). Never throws, fails open to null on any error.
+//
+// Split out from selfLocationPkgRoot() (below) so scripts/doctor.mjs can ask
+// the same question about an ARBITRARY installed hooks directory
+// (~/.claude/hooks, ~/.codex/hooks) instead of only about wherever THIS
+// running module happens to live. doctor needs that to tell "self-location
+// genuinely can't resolve for this install" (the standalone-copy steady
+// state, silence is correct) apart from "self-location would resolve but the
+// provenance sidecar is missing/broken" (a real gap — see CONCERN 4's
+// PKG_ROOT-null-and-silent fix in checkProvenanceSidecar). Exported;
+// scripts/ → hooks/ stays the only allowed import direction.
+export function selfLocationPkgRootFrom(hooksDir) {
+  let ownRealPath;
+  try {
+    ownRealPath = realpathSync(join(hooksDir, 'hypo-shared.mjs'));
+  } catch {
+    return null; // can't even resolve the module at hooksDir — nothing to self-contain against
+  }
+  try {
+    let dir = dirname(hooksDir); // first candidate: the ordinary root, one level above hooks/
+    for (let i = 0; i < 6; i++) {
+      if (isUsablePkgRootLocal(dir) && candidateContainsRunningModule(dir, ownRealPath)) {
+        return dir;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break; // reached filesystem root
+      dir = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function selfLocationPkgRoot() {
+  let hooksDir;
+  try {
+    hooksDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return null; // can't even resolve our own path
+  }
+  return selfLocationPkgRootFrom(hooksDir);
+}
+
+// Copy-time provenance sidecar (`.hypo-provenance.json`, written next to a
+// standalone-copied hooks/ dir by installHooks/applyHookFiles — see
+// scripts/lib/pkg-provenance.mjs, the writer half of this contract) is the
+// ONLY fallback resolvePkgRoot() gets when self-location can't resolve. The
+// filename and the "hypomnema" name check below must stay byte-identical
+// with scripts/lib/pkg-provenance.mjs — hooks can't import scripts/ (no
+// reaching outside hooks/), so the contract is duplicated, not shared.
+//
+// This is accidental-staleness protection, not a security boundary: any
+// process running as this OS user can edit this JSON file (or hypo-shared.mjs
+// itself) freely. It only catches what installHooks/applyHookFiles left
+// unguarded before this fix — a manual-install hooks/ copy left pointing at
+// an old pkgVersion because a skip-then-refresh-the-cache-anyway sequence
+// (init re-run against an unchanged hooks/ dir) recorded a version the copy
+// on disk never actually became.
+//
+// Producer proof, BOTH required before this pkgRoot is trusted:
+//   - the recorded pkgRoot's package.json "name" must be "hypomnema" (not
+//     merely "some usable versioned package.json" — isUsablePkgRootLocal
+//     alone would accept $HOME/package.json from an unrelated project)
+//   - the recorded hypoSharedSha256 must match the SHA-256 of THIS running
+//     hypo-shared.mjs file — ties the sidecar to the exact copy it was
+//     written next to, so a sidecar surviving a partial re-install (new
+//     hooks/*.mjs dropped in, old sidecar left behind) is rejected rather
+//     than silently trusted.
+//
+// Scope, stated honestly: hypoSharedSha256 pins ONE file — this file. A
+// sidecar surviving a re-install that touched some OTHER hook (e.g.
+// hypo-personal-check.mjs got a new version, hypo-shared.mjs itself didn't
+// change a byte) still passes this check and PKG_ROOT still resolves,
+// because the running module — the one thing this function can verify
+// without cost — never changed. Catching that wider drift needs hashing
+// every file hooks.json wires up, which is too expensive to do on every
+// hook load (this function runs on every single hook invocation); that
+// broader, once-per-`doctor`-run check is `hooksDigest`
+// (scripts/lib/pkg-provenance.mjs's computeHooksDigest, verified by
+// scripts/doctor.mjs), deliberately NOT read here.
+const PROVENANCE_FILENAME = '.hypo-provenance.json';
+const EXPECTED_PKG_NAME = 'hypomnema';
+
+function readVerifiedProvenancePkgRoot(hooksDir) {
+  try {
+    const raw = JSON.parse(readFileSync(join(hooksDir, PROVENANCE_FILENAME), 'utf-8'));
+    const { pkgRoot, hypoSharedSha256 } = raw || {};
+    if (!isUsablePkgRootLocal(pkgRoot)) return null;
+    const producerPkgJson = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8'));
+    if (producerPkgJson.name !== EXPECTED_PKG_NAME) return null;
+    if (typeof hypoSharedSha256 !== 'string' || !hypoSharedSha256) return null;
+    const ownHash = createHash('sha256')
+      .update(readFileSync(join(hooksDir, 'hypo-shared.mjs')))
+      .digest('hex');
+    if (ownHash !== hypoSharedSha256) return null;
+    return pkgRoot;
+  } catch {
+    return null;
+  }
+}
+
+// Resolution order: self-location wins whenever it resolves — it is a direct,
+// self-containment-verified fact about the code currently running, not an
+// inference. Only when it cannot resolve (the standalone-copied hooks case
+// above, or a genuine read failure) does the verified provenance sidecar get
+// to answer, checked against the same directory this module is actually
+// running from. The cache (readCachedPkgRoot/hypo-pkg.json) is deliberately
+// NOT a resolution fallback here — a disagreeing provenance sidecar means
+// "stop", not "ask the cache", because the cache is exactly what can be
+// stale (that staleness is this fix's whole premise). readCachedPkgRoot stays
+// in this file only for pkgRootDriftStatus()'s surfacing comparison below.
+function resolvePkgRoot() {
+  const self = selfLocationPkgRoot();
+  if (self) return self;
+  try {
+    const hooksDir = dirname(fileURLToPath(import.meta.url));
+    return readVerifiedProvenancePkgRoot(hooksDir);
+  } catch {
+    return null;
+  }
+}
 export const PKG_ROOT = resolvePkgRoot();
 
+// realpath a path for comparison, falling back to the raw value on any error
+// (missing/unreadable/etc — the comparison then just degrades to a literal
+// string compare, same as before this existed). Never throws.
+function canonicalPath(p) {
+  if (typeof p !== 'string' || !p) return p;
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+// Tri-state comparison between the cache and the code's own resolved
+// location, for the SURFACING decision only (resolvePkgRoot() above already
+// self-corrects PKG_ROOT in memory regardless of this). Three outcomes:
+//   'match'   — cache and self-location agree (or both resolve to nothing
+//               comparable) → any earlier drift mark should be CLEARED.
+//   'drift'   — self-location resolves and DISAGREES with the cache → notify.
+//   'unknown' — self-location could not be resolved at all → leave any
+//               existing mark untouched. This is the PERMANENT steady state
+//               for the npm/manual channel (no package.json ships next to the
+//               standalone-copied hooks), not a rare hiccup — collapsing it
+//               into 'match' would let that channel silently clear a mark it
+//               never had grounds to judge, and collapsing it into 'drift'
+//               would falsely warn a channel with nothing to compare against.
+//
+// The equality check canonicalizes BOTH sides first: the cache may record a
+// symlink alias of the very same physical root selfLocationPkgRoot() just
+// walked to (a symlinked plugin cache dir, or the same /var vs /private/var
+// split candidateContainsRunningModule already has to handle) — a literal
+// string compare would misreport that as drift.
+//
+// Never throws (every helper it calls already fails open).
+export function pkgRootDriftStatus() {
+  const self = selfLocationPkgRoot();
+  if (!self) return { status: 'unknown' };
+  const cached = readCachedPkgRoot();
+  if (canonicalPath(self) === canonicalPath(cached)) return { status: 'match' };
+  return { status: 'drift', cached, self };
+}
+
 // Optional H2 allowlist for hot.md validation.
 // Set HYPO_ALLOWED_HOT_H2=comma,separated,headings to enable.
 const _allowedH2Env = process.env.HYPO_ALLOWED_HOT_H2;
@@ -334,18 +606,30 @@ export function hasAnyTodayLogEntry(hypoDir) {
 }
 
 /**
- * Date strings that count as "today" for freshness checks. Both the local and
- * UTC dates are accepted: Claude writes file dates in the user's local zone,
- * while hypo-hot-rebuild stamps root hot.md with the UTC date. Accepting both
- * removes the ~timezone-offset window where a correctly closed session would
- * otherwise false-block.
+ * Local and UTC calendar-day strings for a given instant. Both matter because
+ * some writers stamp a date in the user's local zone (Claude writing file
+ * content) while others stamp UTC (hypo-hot-rebuild, the session-closed
+ * marker's `closed_at`) — comparing only one representation opens a
+ * ~timezone-offset window where a same-moment date-comparison reads as two
+ * different days. Shared by `freshDates()` (today) and any caller comparing
+ * against an arbitrary past timestamp (e.g. doctor correlating a marker's
+ * `closed_at` against an artifact's local-dated heading).
+ * @param {Date} [date]
+ * @returns {string[]} 1-2 ISO dates (YYYY-MM-DD), local first.
+ */
+export function localAndUtcDates(date = new Date()) {
+  const local = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+  const utc = date.toISOString().slice(0, 10);
+  return local === utc ? [local] : [local, utc];
+}
+
+/**
+ * Date strings that count as "today" for freshness checks. See
+ * {@link localAndUtcDates} for why both representations are accepted.
  * @returns {string[]} 1-2 ISO dates (YYYY-MM-DD), most-relevant first.
  */
 export function freshDates() {
-  const d = new Date();
-  const local = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
-  const utc = d.toISOString().slice(0, 10);
-  return local === utc ? [local] : [local, utc];
+  return localAndUtcDates(new Date());
 }
 
 // Parse a single frontmatter scalar (mirrors hypo-session-start.mjs /
@@ -422,7 +706,11 @@ export function pageUsageGuardCachePath(sessionId, hypoDir) {
   return join(tmpdir(), `hypo-pageusage-guard-${safe}-${h.toString(36)}.json`);
 }
 
-export function pageUsageLoggingAllowed(hypoDir, sessionId) {
+// `probeFn` is test-only: tests inject a fake to control the "did git answer"
+// outcome deterministically instead of racing a real subprocess under shard
+// load. Production callers never pass it, so they always get `runGitCheckIgnore`
+// below, byte-for-byte the same spawnSync call this file always made.
+export function pageUsageLoggingAllowed(hypoDir, sessionId, probeFn) {
   // The load-bearing commit gate is .hypoignore: it is what hypo-auto-stage and
   // commitWikiChanges actually filter on. Re-check it FRESH on every call (it is
   // cheap, no subprocess) so that if coverage is removed mid-session the guard
@@ -439,38 +727,99 @@ export function pageUsageLoggingAllowed(hypoDir, sessionId) {
   }
   if (!hypoIgnored) return false;
 
-  return gitIgnoresPageUsageCached(hypoDir, sessionId);
+  return gitIgnoresPageUsageCached(hypoDir, sessionId, probeFn);
 }
 
 // git check-ignore is the belt signal (defends a manual `git add`); it spawns a
 // subprocess, so cache its result per session. The verdict cached here is only
 // the git signal, never the composite allow decision, so the fresh .hypoignore
 // re-check above always still runs.
-function gitIgnoresPageUsageCached(hypoDir, sessionId) {
+// How long an unanswered probe suppresses the next one. Long enough that a git
+// that is genuinely wedged costs one 10s wait per half-minute instead of one per
+// prompt, short enough that a blip clears on its own well inside a session.
+const PROBE_BACKOFF_MS = 30000;
+
+// The real probe: check-ignore answers with an exit code, 0 = ignored, 1 = not
+// ignored. Split out to a named function so `gitIgnoresPageUsageCached` can take
+// a substitute in tests without touching what production actually spawns.
+function runGitCheckIgnore(hypoDir) {
+  return spawnSync('git', ['-C', hypoDir, 'check-ignore', '-q', '--', PAGE_USAGE_REL], {
+    timeout: 10000,
+  });
+}
+
+function gitIgnoresPageUsageCached(hypoDir, sessionId, probeFn = runGitCheckIgnore) {
+  // Without a session id every caller lands on the same `default` cache file, so
+  // one session's verdict would answer for the next one — and the file outlives
+  // both, sitting in tmpdir with nothing to expire it. A verdict that cannot be
+  // scoped to a session is not cached at all: re-probe every time instead of
+  // serving a stale `true` after .gitignore coverage has been removed.
+  const scoped = Boolean(sessionId);
   const cachePath = pageUsageGuardCachePath(sessionId, hypoDir);
-  try {
-    if (existsSync(cachePath)) {
-      const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
-      if (typeof cached.gitIgnored === 'boolean') return cached.gitIgnored;
+  if (scoped) {
+    try {
+      if (existsSync(cachePath)) {
+        const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+        if (typeof cached.gitIgnored === 'boolean') return cached.gitIgnored;
+        // A recorded outage still stands until it expires. This is what keeps a
+        // wedged git off the UserPromptSubmit path: hypo-lookup calls this before
+        // it prints, so a 10s wait here is 10s of dead prompt, every prompt.
+        if (typeof cached.unavailableUntil === 'number' && Date.now() < cached.unavailableUntil) {
+          return false;
+        }
+      }
+    } catch {
+      // corrupt cache → recompute below
     }
-  } catch {
-    // corrupt cache → recompute below
   }
 
-  let gitIgnored = false;
+  // check-ignore answers with an exit code: 0 = ignored, 1 = not ignored. Every
+  // other outcome means the probe never got to answer — 128 for a fatal git
+  // error (hypoDir not a repo yet), or a null status when the timeout below
+  // fired or the spawn itself failed, which is what a machine under heavy
+  // process load produces. Treating those as a plain `false` is the bug this guards
+  // against: it is indistinguishable from git actually saying "not ignored",
+  // and the verdict then gets cached, so one blip keeps logging disabled for
+  // the rest of the session even after the condition clears.
+  // The bound is here to survive a git that never returns (an index.lock held by
+  // a dead process, a corrupt repo), not to race a busy machine. It used to be
+  // 2s, which a loaded box clears by a hair: instrumenting a one-process-per-suite
+  // run produced eight ETIMEDOUT probes, every one of them landing between 2011ms
+  // and 2254ms. check-ignore on a real vault costs single-digit milliseconds, so
+  // the old bound was three orders of magnitude tighter than the work and was
+  // measuring scheduler latency instead of git. 10s still catches a true hang.
+  let probe = null;
   try {
-    gitIgnored =
-      spawnSync('git', ['-C', hypoDir, 'check-ignore', '-q', '--', PAGE_USAGE_REL], {
-        timeout: 2000,
-      }).status === 0;
+    probe = probeFn(hypoDir);
   } catch {
-    gitIgnored = false;
+    probe = null;
   }
 
-  try {
-    writeFileSync(cachePath, JSON.stringify({ gitIgnored }));
-  } catch {
-    // cache write failure is non-fatal; the git probe just reruns next prompt
+  // Inconclusive → fail closed for this call. The verdict is never cached as an
+  // answer; what gets recorded is that the probe is down, and only until the
+  // backoff expires. So a scheduler blip self-heals within the session, while a
+  // wedged git is waited on once per backoff window rather than once per prompt.
+  if (!probe || (probe.status !== 0 && probe.status !== 1)) {
+    if (scoped) {
+      try {
+        writeFileSync(
+          cachePath,
+          JSON.stringify({ unavailableUntil: Date.now() + PROBE_BACKOFF_MS }),
+        );
+      } catch {
+        // non-fatal; the probe just runs again next prompt
+      }
+    }
+    return false;
+  }
+
+  const gitIgnored = probe.status === 0;
+  if (scoped) {
+    try {
+      writeFileSync(cachePath, JSON.stringify({ gitIgnored }));
+    } catch {
+      // cache write failure is non-fatal; the git probe just reruns next prompt
+    }
   }
   return gitIgnored;
 }
@@ -1270,22 +1619,75 @@ function atomicWriteShared(path, content) {
   renameSync(tmp, path);
 }
 
+// Read the pid the current holder recorded in its lockfile (see withFileLock).
+// Returns null for anything we can't trust as a pid: empty/missing content (a
+// lock written before this pid-recording existed, or already gone), or content
+// that doesn't parse as a positive integer. null means "unknown holder" and the
+// caller falls back to the pre-liveness, mtime-only steal rule.
+function readLockHolderPid(lockPath) {
+  let raw;
+  try {
+    raw = readFileSync(lockPath, 'utf-8').trim();
+  } catch {
+    return null; // vanished/unreadable mid-check — let the caller's own catch handle it
+  }
+  // Canonical decimal only. `Number()` would accept '1e3' and '0x10' as pids,
+  // which contradicts what this function promises its callers: anything we
+  // can't trust is null, not a number we guessed at.
+  if (!/^[1-9][0-9]*$/.test(raw)) return null;
+  const pid = Number(raw);
+  return Number.isSafeInteger(pid) ? pid : null;
+}
+
+// Is `pid` still running? EPERM means it exists but we can't signal it (e.g. a
+// different user) — treat that as alive too, since "can't prove it's dead" must
+// not be steal-eligible.
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
 /**
  * Run `fn` while holding an exclusive lock on `<targetPath>.lock`.
  *
- * Acquire is a spin on `openSync(lock, 'wx')`: EEXIST means another writer holds
- * it, so poll until it frees. A lock whose holder looks dead (mtime older than
- * `staleMs`) is stolen. Steal is recoverable friction in the normal case (the
- * stealer re-reads the committed bytes before writing), but NOT loss-free in two
- * edge cases, both requiring the lock to sit untouched for `staleMs`: (1) a LIVE
- * holder preempted past `staleMs` gets stolen from, so two writers run the
- * critical section and one update is lost; (2) between the stale `statSync` and
- * the `unlinkSync`, the holder can release and a fresh holder grab the same path,
- * whose lock we then remove. `staleMs` is set well above a normal close (seconds)
- * to make both extreme-low-probability. If the lock cannot be acquired within
- * `timeoutMs`, throw so the caller can fall back to the write=proposal gate — for
- * an append that means blocking the close (proposal-pending) with no artifact; the
- * next close re-appends (architecturally consistent with the existing fail-safe).
+ * Acquire is a spin on `linkSync(tmp, lock)`, where `tmp` already holds this
+ * process's pid in full: EEXIST means another writer holds it, so poll until it
+ * frees. Linking a complete file is what makes the lock's content trustworthy —
+ * a lock is never observable in a half-written state, so "no pid in there" always
+ * means a genuine pre-liveness lockfile and never a holder mid-acquire. The lock
+ * file's content is therefore the holder's own pid,
+ * so a lock whose mtime is older than `staleMs` is only stolen once we can also
+ * confirm the recorded holder is no longer running (`process.kill(pid, 0)`). A
+ * LIVE holder preempted past `staleMs` is therefore left alone — its lock is not
+ * stolen, so the second writer instead polls through to `timeoutMs` and throws,
+ * falling back to the write=proposal gate instead of racing the live holder's
+ * critical section (this was case (1) of the old mtime-only rule, and it's what
+ * closes it). A lock with no readable/parseable pid (written before this
+ * recording existed) falls back to the old mtime-only rule so pre-existing
+ * lockfiles from a live process on disk still get treated as steal-eligible once
+ * stale — see `readLockHolderPid`. Every steal, and every steal we refuse because
+ * the holder is alive, is logged to stderr so a preemption or an actual steal is
+ * never silent. One edge remains, unrelated to holder liveness: between the
+ * stale `statSync` and the `unlinkSync`, the holder can release and a fresh
+ * holder grab the same path, whose lock we then remove — `staleMs` is set well
+ * above a normal close (seconds) to make that extreme-low-probability, and it is
+ * out of scope here. Release is symmetric: we only unlink the lock while it still
+ * records OUR pid, so a writer that WAS stolen from never removes the lock of the
+ * holder that replaced it. If the lock cannot be acquired within `timeoutMs`,
+ * throw so the caller can fall back to the write=proposal gate — for an append
+ * that means blocking the close (proposal-pending) with no artifact; the next
+ * close re-appends (architecturally consistent with the existing fail-safe).
+ *
+ * Note what refusing to steal from a live holder trades away: a holder that is
+ * alive but permanently hung is now never stolen from, so every later close
+ * times out too. That is availability loss, not a deadlock (`timeoutMs` still
+ * bounds each attempt), but unlike an ordinary lock timeout it does NOT self-heal
+ * on the next close — it needs the hung process to go away. Losing an append is
+ * silent; blocking one is visible, so this is the direction to fail in.
  *
  * @param {string} targetPath file being guarded (lock is a sibling `.lock`)
  * @param {() => T} fn critical section
@@ -1298,59 +1700,140 @@ export function withFileLock(targetPath, fn, opts = {}) {
   const lockPath = `${targetPath}.lock`;
   mkdirSync(dirname(lockPath), { recursive: true });
   const start = Date.now();
-  let fd;
-  for (;;) {
-    try {
-      fd = openSync(lockPath, 'wx');
-      break;
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      // Held by another writer. Steal ONLY a demonstrably stale lock; otherwise
-      // wait and eventually time out. The stat and the unlink are handled
-      // separately on purpose: an un-removable stale lock (EACCES/EPERM/EBUSY)
-      // and a fresh lock must both fall through to the timeout check — never
-      // `continue` past it, or an un-unlinkable lock spins forever and violates
-      // the timeoutMs → ELOCKTIMEOUT contract (caller falls to the proposal gate).
-      let stale = false;
+  // Publish the lock ATOMICALLY: write the whole pid into a private sibling
+  // first, then `linkSync` it into place. `openSync(lockPath,'wx')` followed by
+  // a write cannot do this — it publishes an EMPTY lock and fills it in after,
+  // and a holder preempted inside that window looks exactly like a pid-less
+  // legacy lock, so a second writer steals it and both run the critical section.
+  // That is the very bug the liveness check exists to close, so the acquire has
+  // to be atomic for the check to mean anything. `link` also gives us the same
+  // EEXIST-if-taken primitive `wx` did, and it leaves nothing behind when the
+  // write fails: no link, no lock.
+  // The staging name is per-call random, and the staging write is exclusive.
+  // A predictable `<lock>.<pid>.tmp` would be reachable again by a later run of
+  // the same pid, and a crash between the link and the staging unlink leaves tmp
+  // and lock as two names for ONE inode — writing the staging file would then
+  // rewrite the live lock's bytes and mtime, resurrecting a dead lock under a
+  // live pid that the liveness check would then protect. Random + `wx` removes
+  // both the collision and the symlink it could otherwise be pointed through.
+  const tmpPath = `${lockPath}.${randomBytes(8).toString('hex')}.tmp`;
+  let staged = false;
+  // The live-holder refusal is re-evaluated on every poll, but it is one event,
+  // not `timeoutMs / pollMs` of them. Log each once per acquire or a single
+  // preemption buries the hook's stderr under ~100 identical lines.
+  let loggedLiveHolder = false;
+  let loggedSteal = false;
+  try {
+    for (;;) {
       try {
-        // Steal a lock whose holder looks dead. Loss-free unless the holder is
-        // actually live-but-preempted past staleMs (see JSDoc edge cases).
-        stale = Date.now() - statSync(lockPath).mtimeMs > staleMs;
-      } catch (statErr) {
-        if (statErr.code === 'ENOENT') continue; // lock vanished; retry create now
-        throw statErr; // unexpected stat failure — surface it, don't mask
-      }
-      if (stale) {
+        if (!staged) {
+          try {
+            writeFileSync(tmpPath, String(process.pid), { flag: 'wx' });
+            staged = true;
+          } catch (stageErr) {
+            // Staging fails for the same reason acquisition does — an unwritable
+            // directory — and `openSync(lock,'wx')` used to report exactly that as
+            // EEXIST whenever a lock was already sitting there, sending it down the
+            // contention path. Preserve that: contend if a lock exists, and surface
+            // a genuine write failure otherwise rather than masking it as a timeout.
+            if (!existsSync(lockPath)) throw stageErr;
+            throw Object.assign(new Error('lock-contended'), { code: 'EEXIST' });
+          }
+        }
+        // Kept separate from staging on purpose: EPERM/EMLINK from the link are
+        // real failures, not contention, and must not decay into ELOCKTIMEOUT.
+        linkSync(tmpPath, lockPath);
+        break;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        // Held by another writer. Steal ONLY a demonstrably stale lock; otherwise
+        // wait and eventually time out. The stat and the unlink are handled
+        // separately on purpose: an un-removable stale lock (EACCES/EPERM/EBUSY)
+        // and a fresh lock must both fall through to the timeout check — never
+        // `continue` past it, or an un-unlinkable lock spins forever and violates
+        // the timeoutMs → ELOCKTIMEOUT contract (caller falls to the proposal gate).
+        let stale = false;
         try {
-          unlinkSync(lockPath);
-          continue; // stole it; retry the create immediately
-        } catch (unlinkErr) {
-          if (unlinkErr.code === 'ENOENT') continue; // another stealer won; retry
-          // Cannot remove it: do NOT spin — fall through to timeout/sleep so
-          // acquisition eventually throws ELOCKTIMEOUT instead of hanging.
+          // Steal-eligible by age alone; liveness is checked separately below
+          // before we actually act on it.
+          stale = Date.now() - statSync(lockPath).mtimeMs > staleMs;
+        } catch (statErr) {
+          if (statErr.code === 'ENOENT') continue; // lock vanished; retry create now
+          throw statErr; // unexpected stat failure — surface it, don't mask
         }
+        if (stale) {
+          const holderPid = readLockHolderPid(lockPath);
+          if (holderPid !== null && isPidAlive(holderPid)) {
+            // LIVE holder preempted past staleMs: do NOT steal. Surface it so the
+            // preemption is visible, then fall through to the poll/timeout path
+            // below instead of racing a second writer into the critical section.
+            if (!loggedLiveHolder) {
+              console.error(
+                `[hypomnema] withFileLock: NOT stealing ${lockPath} — holder pid ${holderPid} is still alive past staleMs=${staleMs}`,
+              );
+              loggedLiveHolder = true;
+            }
+            stale = false;
+          } else if (!loggedSteal) {
+            // Also once per acquire: an un-removable stale lock re-enters this
+            // branch on every poll, and the steal is one event either way.
+            console.error(
+              `[hypomnema] withFileLock: stealing stale lock ${lockPath}` +
+                (holderPid !== null
+                  ? ` (holder pid ${holderPid} is no longer running)`
+                  : ' (no readable holder pid — pre-liveness lockfile)'),
+            );
+            loggedSteal = true;
+          }
+        }
+        if (stale) {
+          try {
+            unlinkSync(lockPath);
+            continue; // stole it; retry the create immediately
+          } catch (unlinkErr) {
+            if (unlinkErr.code === 'ENOENT') continue; // another stealer won; retry
+            // Cannot remove it: do NOT spin — fall through to timeout/sleep so
+            // acquisition eventually throws ELOCKTIMEOUT instead of hanging.
+          }
+        }
+        if (Date.now() - start > timeoutMs) {
+          // Tagged so callers can distinguish "could not get the lock" (fall to the
+          // proposal gate) from a real fn() write error (mkdir/openSync/disk-full),
+          // which must NOT be masked as a timeout.
+          const e = new Error(`lock-timeout: ${lockPath}`);
+          e.code = 'ELOCKTIMEOUT';
+          throw e;
+        }
+        sleepSync(pollMs);
       }
-      if (Date.now() - start > timeoutMs) {
-        // Tagged so callers can distinguish "could not get the lock" (fall to the
-        // proposal gate) from a real fn() write error (mkdir/openSync/disk-full),
-        // which must NOT be masked as a timeout.
-        const e = new Error(`lock-timeout: ${lockPath}`);
-        e.code = 'ELOCKTIMEOUT';
-        throw e;
-      }
-      sleepSync(pollMs);
     }
-  }
-  try {
-    return fn();
   } finally {
+    // The sibling is only ever a staging file: once linked, the lock IS the
+    // link, and on every failure path it must not survive as litter.
     try {
-      closeSync(fd);
+      unlinkSync(tmpPath);
     } catch {
-      /* fd already gone */
+      /* never created, or already gone */
     }
+  }
+  try {
+    return fn();
+  } finally {
+    // Only remove the lock if it is still OURS. Recording the pid makes this
+    // checkable: if we were stolen from (a legacy pid-less lock of ours, or the
+    // stat/unlink window below), the path now holds a DIFFERENT holder's lock and
+    // unlinking it unconditionally would hand a third writer the critical section
+    // while that holder is still inside it. Leaving a foreign lock alone costs
+    // nothing — its own holder releases it, or it goes stale.
     try {
-      unlinkSync(lockPath);
+      const stillOurs = readLockHolderPid(lockPath);
+      if (stillOurs === process.pid) unlinkSync(lockPath);
+      else if (existsSync(lockPath))
+        console.error(
+          `[hypomnema] withFileLock: not releasing ${lockPath} — it now holds ${
+            stillOurs === null ? 'no readable pid' : `pid ${stillOurs}`
+          }, so ours was stolen`,
+        );
     } catch {
       /* lock already stolen/removed */
     }
@@ -1464,6 +1947,39 @@ function syncStatePath(hypoDir) {
   return join(hypoDir, '.cache', 'sync-state.json');
 }
 
+/**
+ * Classify a sync-state `op` into the guidance branch it needs. Centralized
+ * here — rather than each surface repeating its own string check — because
+ * hypo-session-start.mjs's syncStateNotice and doctor.mjs's checkSyncState
+ * used to each carry their own comparison, and drifted: session-start's
+ * exact `=== 'conflict'` check silently missed 'conflict-unresolved' (the
+ * MORE dangerous op, since the abort itself failed and the tree may still be
+ * half-merged) and fell through to the generic "last sync failed" line,
+ * while doctor's `startsWith('conflict')` already caught it. Both
+ * callers now branch on this single function's return value, so they cannot
+ * silently diverge on WHICH op gets which treatment again — only on the
+ * prose each renders for a given branch.
+ *
+ * Both known ops are matched by EXACT string, not startsWith: a future
+ * `conflict-*` value this function has never seen (e.g. a new syncRemote
+ * failure mode added later) must not silently fall into either known
+ * bucket. 'conflict' asserts the abort succeeded and local work is safely
+ * committed; 'conflict-unresolved' asserts the abort itself failed. Neither
+ * claim is known to hold for an op nobody has written a branch for yet, so
+ * it gets its own conservative 'unknown-conflict' bucket instead of
+ * inheriting either surface's reassurance by accident.
+ *
+ * @param {string} op
+ * @returns {'conflict-unresolved'|'conflict'|'unknown-conflict'|'other'}
+ */
+export function classifySyncOp(op) {
+  const s = String(op || '');
+  if (s === 'conflict-unresolved') return 'conflict-unresolved';
+  if (s === 'conflict') return 'conflict';
+  if (s.startsWith('conflict')) return 'unknown-conflict';
+  return 'other';
+}
+
 /**
  * Append a sync failure entry. Best-effort — never throws, since a failed
  * failure-log must not break the Stop hook that calls it.
@@ -1528,6 +2044,7 @@ export function syncRemote(hypoDir) {
     const pull = git('pull', '--no-rebase', '-q');
     if (pull.status === 0) {
       result.pulled = true;
+      recordSyncSuccess(hypoDir, 'pull');
     } else {
       // A merge conflict leaves unmerged index entries; a network/auth failure
       // leaves none. Only the former must be aborted to keep the tree clean.
@@ -1552,39 +2069,390 @@ export function syncRemote(hypoDir) {
       appendSyncFailure(hypoDir, 'pull', pull.stderr || pull.stdout);
     }
     const push = git('push');
-    if (push.status === 0) result.pushed = true;
-    else appendSyncFailure(hypoDir, 'push', push.stderr || push.stdout);
+    if (push.status === 0) {
+      result.pushed = true;
+      recordSyncSuccess(hypoDir, 'push');
+    } else appendSyncFailure(hypoDir, 'push', push.stderr || push.stdout);
   } catch {
     // best-effort — never break the Stop hook
   }
   return result;
 }
 
+// ── touched-paths (scope the auto-commit to session-touched paths) ───────────
+//
+// The old commitWikiChanges swept the ENTIRE working tree: in a shared
+// multi-project vault with concurrent Claude Code sessions, another session's
+// staged/dirty files got committed and pushed by THIS session's Stop hook, and
+// the human-authored commit message was clobbered. The fix is to accumulate,
+// per session_id, the vault-relative paths this session actually touched, and
+// have commitWikiChanges commit only that scope.
+//
+// Sources that feed the accumulator:
+//   - hypo-auto-stage.mjs (PostToolUse): every Write/Edit/MultiEdit to a file
+//     under the vault.
+//   - hypo-hot-rebuild.mjs (Stop, runs BEFORE auto-commit): hot.md and log.md,
+//     which are hook-generated, not user Write/Edit — without this a scope
+//     built from Write/Edit alone would drop them from the scoped commit.
+//
+// No session_id → never accumulate, and never fall back to a shared "default"
+// bucket: a path recorded under the wrong key could leak between sessions.
+
+/** Directory holding one session's cache artifacts, incl. touched-paths.json. */
+function sessionCacheDir(hypoDir, sessionId) {
+  return join(hypoDir, '.cache', 'sessions', sanitizeSessionId(sessionId));
+}
+
+/** @returns {string} path to a session's accumulated touched-paths JSON array. */
+export function touchedPathsPath(hypoDir, sessionId) {
+  return join(sessionCacheDir(hypoDir, sessionId), 'touched-paths.json');
+}
+
 /**
- * Stage + commit every non-.hypoignore change in the wiki. Does NOT pull/push —
- * remote sync stays in the auto-commit Stop hook (commit is local + cheap; sync is
+ * Read the raw touched-paths JSON array off disk. Caller's responsibility to
+ * hold the per-session lock first — this has no locking of its own.
+ *
+ * Absent and unreadable are different answers, and callers MUST branch on
+ * the difference: a genuinely absent (or genuinely empty) file returns `[]`
+ * — safe to treat as "nothing accumulated". A file that exists but fails to
+ * read or parse returns `null` — NOT the same as empty. A caller that
+ * conflates the two (codex FIX 1) and then does a set-difference clear on
+ * `null`-as-`[]` will compute "nothing left" and delete the file outright,
+ * silently losing every pending path to a transient I/O or parse error.
+ *
+ * @returns {string[]|null} the array, or `null` on a read/parse failure
+ */
+function readTouchedPathsFile(path) {
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return Array.isArray(parsed) ? parsed.filter((p) => typeof p === 'string' && p) : null;
+  } catch {
+    return null; // corrupt/unreadable — NOT the same as empty; see above
+  }
+}
+
+/**
+ * Accumulate vault-relative touched paths for `sessionId`. Best-effort,
+ * dedup-on-insert, JSON array (not delimiter-joined — survives non-ASCII and
+ * any byte a filename can legally hold). No-op without a session_id: never
+ * accumulate into a shared bucket.
+ *
+ * Read-merge-write is guarded by the per-session file lock (the SAME lock
+ * `drainTouchedPaths` takes), so a PostToolUse hook accumulating concurrently
+ * with the Stop-chain drain can never lose a path to either a lost update
+ * (two writers merging from the same stale read) or a drain racing between
+ * this function's read and its write.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @param {string|string[]} relPaths one or more vault-relative paths
+ */
+export function recordTouchedPaths(hypoDir, sessionId, relPaths) {
+  if (!sessionId) return;
+  const incoming = (Array.isArray(relPaths) ? relPaths : [relPaths]).filter(
+    (p) => typeof p === 'string' && p.length > 0,
+  );
+  if (incoming.length === 0) return;
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    withFileLock(path, () => {
+      const current = readTouchedPathsFile(path);
+      // A corrupt/unreadable file (current === null) is recovered from here,
+      // not preserved: an accumulate is additive by nature (there is nothing
+      // salvageable to merge with), so starting fresh from `incoming` is the
+      // correct best-effort behavior — unlike clearTouchedPaths, where the
+      // same `null` MUST NOT be treated as empty (see readTouchedPathsFile).
+      const merged = new Set(current === null ? [] : current);
+      for (const p of incoming) merged.add(p);
+      atomicWriteShared(path, JSON.stringify([...merged]));
+    });
+  } catch {
+    // best-effort: a hook must never fail a tool call over a cache write
+    // (includes a lock-timeout — a dropped accumulation here is the same
+    // fail-safe shape as every other best-effort cache write in this file).
+  }
+}
+
+/**
+ * Read and clear a session's accumulated touched paths in one step — "drain",
+ * not "read", because the caller is expected to consume the WHOLE set
+ * unconditionally. Kept for callers that genuinely want that (e.g. a
+ * probe/inspection path); the Stop-chain auto-commit does NOT use this —
+ * see commitTouchedPaths below, which holds ONE lock across a peek, the
+ * commit itself, and a clear scoped to exactly what committed, so neither a
+ * commit failure nor a same-path race loses anything.
+ *
+ * Guarded by the SAME per-session file lock every touched-paths mutation
+ * takes: the read-then-remove here is mutually exclusive with a concurrent
+ * accumulate or commitTouchedPaths call.
+ *
+ * A read/parse failure is NOT treated as an empty set to be cleared: like
+ * clearTouchedPaths and commitTouchedPaths, a corrupt/unreadable file
+ * (readTouchedPathsFile returns `null`) is left on disk untouched — never
+ * deleted — so a transient I/O or parse error can't erase a set that a human
+ * or a later pass could still recover. Drain returns `[]` in that case
+ * (nothing safely consumable), but does not remove the file.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @returns {string[]} vault-relative paths, deduped; [] when absent, corrupt, or no session_id
+ */
+export function drainTouchedPaths(hypoDir, sessionId) {
+  if (!sessionId) return [];
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const result = readTouchedPathsFile(path);
+      if (result === null) return []; // corrupt/unreadable: leave the file for inspection, never delete
+      try {
+        rmSync(path, { force: true });
+      } catch {
+        // best-effort
+      }
+      return result;
+    });
+  } catch {
+    // lock-timeout (or an unexpected lock error): fail closed to "nothing
+    // drained" rather than risk reading concurrently with a writer. The set
+    // stays on disk untouched, so it is still there for the next drain.
+    return [];
+  }
+}
+
+/**
+ * Read a session's accumulated touched paths WITHOUT clearing them. Kept as
+ * a standalone probe for callers that just want to inspect the set; the
+ * Stop-chain auto-commit does NOT call this on its own — see
+ * commitTouchedPaths, which performs an equivalent internal read but holds
+ * the lock through the commit and clear that follow it too.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @returns {string[]} vault-relative paths, deduped; [] when absent, corrupt,
+ *   no session_id, or a lock-timeout (fails closed to "nothing to commit" —
+ *   the set stays on disk, untouched, for the next Stop)
+ */
+export function peekTouchedPaths(hypoDir, sessionId) {
+  if (!sessionId) return [];
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const result = readTouchedPathsFile(path);
+      return result === null ? [] : result;
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Remove exactly `paths` from a session's touched-paths set — a set
+ * difference, not a clear, and NOT a drain: any path a concurrent
+ * PostToolUse (or Stop-chain generator) accumulated before this call is read
+ * fresh under the SAME lock and therefore survives, because it was never in
+ * `paths` to begin with.
+ *
+ * Called only after commitWikiChanges has ACTUALLY committed `paths` (or
+ * confirmed there was nothing to commit) — never on a commit failure.
+ *
+ * Two failure modes this function must not turn into data loss (codex FIX 1
+ * + FIX 2 review):
+ *
+ *   - A read/parse failure on the touched-paths file (readTouchedPathsFile
+ *     returns `null`, NOT `[]`) must NOT be treated as "nothing left" — that
+ *     would make the set difference below compute an empty remainder and
+ *     DELETE the file outright on a transient I/O or parse error, losing
+ *     every pending path. On `null`, this function does nothing at all:
+ *     no write, no delete, the file is left exactly as it was.
+ *   - If this clear itself fails (lock-timeout, I/O) after a successful
+ *     read, the already-committed paths simply stay in the file: the next
+ *     Stop re-peeks them and re-runs commitWikiChanges, which is a clean
+ *     no-op (INTERSECT against a tree with no more changes at those paths
+ *     yields an empty scoped set). Over-retention is safe by construction —
+ *     it can never lose a path, only a commit failure (handled by leaving
+ *     the file alone entirely, see commitTouchedPaths) can.
+ *
+ * Standalone use of peekTouchedPaths + clearTouchedPaths as two SEPARATE
+ * lock acquisitions still carries the same-path race codex FIX 2 describes
+ * (a write between the two calls is indistinguishable from the one already
+ * peeked, since the set only tracks path presence, not a generation/version
+ * per path) — that is exactly why the Stop hook uses commitTouchedPaths
+ * instead, which holds ONE lock across the whole peek→commit→clear window
+ * so no write can land inside it at all.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @param {string[]} paths the exact paths that were just committed
+ */
+export function clearTouchedPaths(hypoDir, sessionId, paths) {
+  if (!sessionId) return;
+  const toRemove = new Set((Array.isArray(paths) ? paths : []).filter(Boolean));
+  if (toRemove.size === 0) return;
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    withFileLock(path, () => {
+      const current = readTouchedPathsFile(path);
+      if (current === null) return; // FIX 1: never delete/write on a read failure
+      const remaining = current.filter((p) => !toRemove.has(p));
+      if (remaining.length === 0) {
+        try {
+          rmSync(path, { force: true });
+        } catch {
+          // best-effort
+        }
+      } else {
+        atomicWriteShared(path, JSON.stringify(remaining));
+      }
+    });
+  } catch {
+    // lock-timeout or unexpected error: leave the file as-is. Safe per the
+    // over-retention argument above — the committed paths simply linger
+    // until a later clear (or drain) removes them, at worst causing a
+    // future no-op re-commit attempt, never a lost path.
+  }
+}
+
+/**
+ * Peek a session's touched paths, run `commitFn(paths)` (expected to be
+ * `commitWikiChanges` or an equivalent), and — only when it reports
+ * `committed: true` — clear `paths` from the touched-paths set, ALL under
+ * ONE hold of the per-session file lock (codex FIX 2). This is what the
+ * Stop-chain auto-commit uses instead of calling peekTouchedPaths,
+ * commitFn, and clearTouchedPaths as three separate steps.
+ *
+ * Holding one lock across peek → commit → clear (rather than acquiring and
+ * releasing it three times, with the commit itself unlocked in between)
+ * closes a same-path race: without it, a `recordTouchedPaths` call for a
+ * path already in the just-peeked set could land in the window between the
+ * commit and the clear. Since the touched-paths set only tracks path
+ * PRESENCE (no per-path version/generation), that accumulate call is
+ * indistinguishable from the one already peeked — the clear would remove it
+ * anyway, silently orphaning a real edit that was never actually committed
+ * (it landed on disk after `git commit` already ran, but the touched-paths
+ * record of it just got wiped). With one continuous lock hold, that
+ * accumulate call either fully precedes the peek (so it's included in THIS
+ * commit, since commitWikiChanges reads live git status, not a cached
+ * snapshot) or fully follows the clear (so it's untouched, waiting for the
+ * next Stop) — there is no window where it can land in between.
+ *
+ * Lock order stays vault → per-session everywhere in this codebase (the
+ * Stop hook takes the vault lock before calling this; accumulation only
+ * ever takes the per-session lock, never the vault lock), so holding the
+ * per-session lock for the whole commit here introduces no new ordering and
+ * no deadlock risk.
+ *
+ * FIX 1 (read/parse failure) applies here too: a corrupt/unreadable
+ * touched-paths file is never treated as empty. `commitFn` still runs (with
+ * an empty scope — a safe no-op through commitWikiChanges), but nothing is
+ * ever written to the corrupt file; it is left exactly as it was for a
+ * human or a future recovery pass to look at.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @param {(paths: string[]) => {committed: boolean, [k: string]: unknown}} commitFn
+ * @returns {{committed: boolean, [k: string]: unknown}} whatever `commitFn` returned,
+ *   or `{committed: false, reason: 'touched-paths-lock-timeout'}` if the lock
+ *   itself could not be acquired (commitFn never ran; the file is untouched)
+ */
+export function commitTouchedPaths(hypoDir, sessionId, commitFn) {
+  if (!sessionId) return commitFn([]);
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      const current = readTouchedPathsFile(path);
+      if (current === null) {
+        // FIX 1: a read/parse failure is not "empty" — commit nothing this
+        // round (a safe no-op scope) and leave the corrupt file untouched,
+        // rather than let a downstream clear compute "nothing left" and
+        // delete it.
+        return commitFn([]);
+      }
+      const result = commitFn(current);
+      if (result && result.committed && current.length > 0) {
+        // Still under the SAME lock acquired above: no recordTouchedPaths
+        // call for this session can have landed since `current` was read
+        // (it takes this exact lock too), so the set on disk right now is
+        // EXACTLY `current` — clearing it needs no re-read or set
+        // difference, just remove what we already know is the whole thing.
+        try {
+          rmSync(path, { force: true });
+        } catch {
+          // best-effort: the committed paths just linger on disk; the next
+          // Stop re-peeks them and re-runs commitFn, a clean no-op.
+        }
+      }
+      return result;
+    });
+  } catch {
+    // Lock-timeout (or an unexpected lock error): never entered the
+    // critical section, so commitFn never ran and nothing was peeked or
+    // cleared. The touched-paths file is untouched on disk, and the next
+    // Stop retries this session's commit from the same scope.
+    return { committed: false, reason: 'touched-paths-lock-timeout' };
+  }
+}
+
+/**
+ * The lock target both commit loci (hypo-auto-commit.mjs Stop hook,
+ * crystallize.mjs --apply-session-close) hold while staging+committing (and,
+ * for the Stop hook, syncing) the vault, so two concurrent sessions on a
+ * shared vault never interleave `git add`/`git commit`/`git pull`/`git push`.
+ * A stable, non-content path — withFileLock only ever touches its `.lock`
+ * sibling, this file itself is never created.
+ */
+export function vaultCommitLockTarget(hypoDir) {
+  return join(hypoDir, '.cache', 'vault-commit');
+}
+
+/** `projects/<slug>/...` → `<slug>`; anything else → its first path segment. */
+function projectOfPath(relPath) {
+  const parts = relPath.split('/');
+  if (parts[0] === 'projects' && parts.length > 1 && parts[1]) return parts[1];
+  return parts[0] || relPath;
+}
+
+/**
+ * Stage + commit ONLY the caller-supplied `paths`, intersected with what is
+ * actually changed on disk right now. Does NOT pull/push; remote
+ * sync stays in the auto-commit Stop hook (commit is local + cheap; sync is
  * network + soft-fail). Shared by hypo-auto-commit.mjs and crystallize.mjs's
  * --apply-session-close path so the .hypoignore staging filter cannot diverge
  * between the two commit loci.
  *
- * "Nothing to commit" (clean tree, or only .hypoignore'd changes) is SUCCESS, not
- * failure — the caller's tree is already in the committed state it wanted.
+ * The caller supplies the scope; this function never re-derives it from the
+ * whole tree. `paths` absent/empty is a clean no-op (`scoped: 0`), not an
+ * error and not a whole-tree fallback — this is how a caller with nothing to
+ * contribute (e.g. no session_id, so nothing was accumulated) skips cleanly.
+ *
+ * The authoritative scope is INTERSECT(paths, currently-changed): a stale
+ * entry (already committed elsewhere, or never actually changed) is dropped
+ * silently rather than erroring. `.hypoignore` filtering, the staged
+ * re-derivation, the commit-message count, and the final commit all use this
+ * SAME scoped set — no step here may widen back to whole-tree, or another
+ * session's dirty/staged files could slip back in through any one of them.
+ *
+ * "Nothing to commit" (empty scope, or only .hypoignore'd changes) is
+ * SUCCESS, not failure — the caller's tree is already in the state it wanted.
  *
  * @param {string} hypoDir
- * @returns {{committed: boolean, reason?: string}} committed:true when a commit was
- *   created OR nothing needed committing; committed:false (with reason) on a real
- *   failure: not a git repo, or git status/add/commit erroring.
+ * @param {string[]} [paths] vault-relative paths this caller wrote/owns this close
+ * @returns {{committed: boolean, scoped?: number, reason?: string}} committed:true
+ *   when a commit was created OR nothing needed committing (scoped:0 in the
+ *   latter case); committed:false (with reason) on a real failure: not a git
+ *   repo, or git status/add/commit erroring.
  */
-export function commitWikiChanges(hypoDir) {
+export function commitWikiChanges(hypoDir, paths) {
   const git = (...args) =>
     spawnSync('git', ['-C', hypoDir, ...args], { encoding: 'utf-8', timeout: 30000 });
   if (git('rev-parse', '--is-inside-work-tree').status !== 0)
     return { committed: false, reason: `not a git repository: ${hypoDir}` };
-  // `-z`: NUL-separated records with verbatim paths — no surrounding quotes and
-  // no octal escaping, so non-ASCII paths (Korean page names are normal input
-  // here) survive intact. Without it, `core.quotepath=true` (the default) yields
-  // `"pages/\355\225\234\352\270\200.md"` and the old quote-strip parser fed that
-  // literal, non-existent path to `git add` — failing the whole commit.
+
+  const supplied = new Set(
+    (Array.isArray(paths) ? paths : []).filter((p) => typeof p === 'string' && p.length > 0),
+  );
+  if (supplied.size === 0) return { committed: true, scoped: 0 };
+
   // `-z`: NUL-separated records with verbatim paths — no surrounding quotes and
   // no octal escaping, so non-ASCII paths (Korean page names are normal input
   // here) survive intact. Without it, `core.quotepath=true` (the default) yields
@@ -1596,41 +2464,85 @@ export function commitWikiChanges(hypoDir) {
   // `.hypoignore` is the project privacy boundary. `git add -A` ignores it, so
   // enumerate changed paths, drop ignored ones, then stage explicitly.
   const ignorePatterns = loadHypoIgnore(hypoDir);
-  const paths = [];
+  const scoped = []; // pathspec for `git add -A` — worktree/index paths only
+  const commitScope = []; // pathspec for the final diff/commit --only (superset)
   const records = (porcelain.stdout || '').split('\0');
   for (let i = 0; i < records.length; i++) {
     const rec = records[i];
     if (!rec) continue;
     const xy = rec.slice(0, 2);
     const file = rec.slice(3); // `XY <path>`; the destination path for a rename/copy
+    const isRename = xy[0] === 'R' || xy[1] === 'R';
     // A rename OR copy emits two records (`to\0from`); consume the trailing
     // `from`. Copy `C` records only appear under `status.renames=copies`, but
     // when they do, missing this skip feeds the `from` path to `git add` as a
     // bogus pathspec — the exact auto-commit failure this parser fixes.
-    if (xy[0] === 'R' || xy[1] === 'R' || xy[0] === 'C' || xy[1] === 'C') i++;
+    let fromFile = null;
+    if (isRename || xy[0] === 'C' || xy[1] === 'C') {
+      i++;
+      fromFile = records[i] || null;
+    }
     if (!file) continue;
+    if (!supplied.has(file)) continue; // out of this caller's scope
     if (ignorePatterns.length > 0 && isIgnored(join(hypoDir, file), hypoDir, ignorePatterns))
       continue;
-    paths.push(file);
+    scoped.push(file);
+    commitScope.push(file);
+    // A rename's `from` path is the SAME change as its destination — without
+    // it, `git commit --only` on the destination alone commits the addition
+    // but leaves the source's deletion staged as residue (a git --only
+    // quirk, verified). It is NOT added to `git add -A` (the deletion is
+    // already staged by the rename itself, and its worktree entry is gone —
+    // `git add -A -- <a gone-and-already-staged path>` errors "did not match
+    // any files"), only to the commit's pathspec. A copy's `from` is
+    // independently-owned, still-existing content, so it is NOT auto-pulled
+    // in at all: the caller must name it explicitly if it wants it in scope.
+    if (isRename && fromFile) commitScope.push(fromFile);
   }
-  if (paths.length > 0) {
-    const add = git('add', '--', ...paths);
+  if (scoped.length === 0 && commitScope.length === 0) return { committed: true, scoped: 0 };
+
+  if (scoped.length > 0) {
+    const add = git('add', '-A', '--', ...scoped);
     if (add.status !== 0)
       return {
         committed: false,
         reason: `git add failed: ${(add.stderr || '').trim() || 'unknown'}`,
       };
   }
-  const staged = git('diff', '--cached', '--name-only').stdout?.trim() || '';
-  if (!staged) return { committed: true }; // nothing to commit = success (idempotent)
+
+  // Re-derive from what actually landed in the index, bounded by the SAME
+  // pathspec (commitScope, the rename-aware superset of `scoped`) — this step
+  // must not widen back to whole-tree either, or another session's already-
+  // staged file would slip into the commit here.
+  const staged = git('diff', '--cached', '--name-only', '-z', '--', ...commitScope);
+  const stagedFiles = (staged.stdout || '').split('\0').filter(Boolean);
+  if (stagedFiles.length === 0) return { committed: true, scoped: 0 };
+
+  const projects = new Set(stagedFiles.map(projectOfPath));
   const today = new Date().toISOString().slice(0, 10);
-  const commit = git('commit', '-m', `auto: ${today} wiki update`);
+  const msg = `auto: ${today} wiki update (${stagedFiles.length} paths across ${projects.size} projects)`;
+
+  // `git commit --only -- <paths>` (first use of --only in this repo): commits
+  // ONLY the staged changes under this pathspec, ignoring anything else
+  // staged in the index — e.g. another session's own staged-but-uncommitted
+  // work sharing this working tree. A bare `git commit -m` would sweep in
+  // every staged path, defeating the whole point of the scoped set above.
+  //
+  // Pathspec is `commitScope`, NOT `stagedFiles`: `git diff --name-only`
+  // collapses a rename to its destination alone (rename detection folds the
+  // pair into one line), so re-deriving the commit's own pathspec from that
+  // output would silently drop the `from` path again and reproduce the
+  // exact `--only`-leaves-the-deletion-staged residue this function's rename
+  // handling exists to avoid (verified). `stagedFiles` still governs the
+  // empty-scope check and the N/M count above — both correct as "how many
+  // logical changes", where a rename is rightly one.
+  const commit = git('commit', '--only', '-m', msg, '--', ...commitScope);
   if (commit.status !== 0)
     return {
       committed: false,
       reason: `git commit failed: ${(commit.stderr || '').trim() || 'unknown'}`,
     };
-  return { committed: true };
+  return { committed: true, scoped: stagedFiles.length };
 }
 
 /**
@@ -1661,6 +2573,134 @@ export function clearSyncState(hypoDir) {
   }
 }
 
+// ── sync-last-success ────────────────────────────────────────
+// `.cache/sync-last-success.json` is a single JSON object, PER-OPERATION:
+//   { "pull": {"timestamp": "<ISO>", "host": "<os.hostname()>"},
+//     "push": {"timestamp": "<ISO>", "host": "<...>"} }
+// Either key may be absent (pull-only or push-only history). Deliberately
+// separate from sync-state.json: that file is failure-only and gets wiped
+// wholesale on recovery (clearSyncState), so a success record living there
+// would be erased by the very thing it is meant to survive. syncRemote()
+// records here on a successful pull/push; session-start's independent
+// `git pull --ff-only` records a pull here too, so doctor never reports
+// "never synced" right after a healthy startup pull. doctor reads it via
+// readSyncLastSuccess; schema + parsing live here only.
+//
+// Scope: `.cache/` is gitignored (templates/gitignore), same as
+// sync-state.json — this file never syncs across machines, so there is no
+// cross-machine merge to protect. The lock below only has to cover the
+// same-machine case: two concurrent processes on one machine (a pull-writer
+// and a push-writer, or two overlapping sessions). `host` is kept per record
+// purely for provenance (which machine last recorded the op), not because a
+// remote write could ever land here.
+
+/** @returns {string} path to the sync-last-success JSON file for a wiki root. */
+function syncLastSuccessPath(hypoDir) {
+  return join(hypoDir, '.cache', 'sync-last-success.json');
+}
+
+/**
+ * A valid last-success record: `{timestamp: string, host: string}`. Anything
+ * else (wrong type, missing field, non-object) is malformed.
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function isValidSyncSuccessRecord(v) {
+  return (
+    v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    typeof v.timestamp === 'string' &&
+    v.timestamp.trim().length > 0 &&
+    typeof v.host === 'string' &&
+    v.host.trim().length > 0
+  );
+}
+
+/**
+ * Read last-success records. A missing file means "never synced" (not an
+ * error) — the caller distinguishes that from a parse failure via
+ * `parseError`. A present `pull`/`push` field that does not match the
+ * `{timestamp, host}` shape (including an empty/whitespace-only timestamp or
+ * host — a technically-typed but content-free record) is dropped from `data`
+ * (never surfaced as if it were a real record) AND flags `parseError: true`,
+ * so the caller warns ("cannot parse ... inspect manually") instead of
+ * silently rendering `undefined` or an empty value — same corrupt-file
+ * handling as sync-state.json. An unrecognized top-level key (anything other
+ * than `pull`/`push`) likewise flags the whole file as corrupt: this schema
+ * has exactly two legal keys, so a third one is evidence of a hand-edit or a
+ * future/foreign writer, not a shape this reader should quietly tolerate.
+ *
+ * @param {string} hypoDir
+ * @returns {{data: {pull?: {timestamp: string, host: string}, push?: {timestamp: string, host: string}}, parseError: boolean}}
+ */
+export function readSyncLastSuccess(hypoDir) {
+  const path = syncLastSuccessPath(hypoDir);
+  if (!existsSync(path)) return { data: {}, parseError: false };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+      return { data: {}, parseError: true };
+    let malformed = Object.keys(parsed).some((k) => k !== 'pull' && k !== 'push');
+    const data = {};
+    for (const op of ['pull', 'push']) {
+      if (parsed[op] === undefined) continue;
+      if (isValidSyncSuccessRecord(parsed[op])) data[op] = parsed[op];
+      else malformed = true; // drop the bad field; flag the file as corrupt
+    }
+    return { data, parseError: malformed };
+  } catch {
+    return { data: {}, parseError: true };
+  }
+}
+
+/**
+ * Record a successful pull or push. Concurrency-safe on the same machine:
+ * takes the vault file lock on the target path, re-reads the CURRENT file
+ * under the lock, updates only the given op's field (the other op's existing
+ * value survives — a same-machine concurrent pull-writer and push-writer must
+ * not erase each other), then commits via temp-write + rename so a crash or a
+ * concurrent read never sees a half-written file. `.cache/` is gitignored, so
+ * this file never syncs across machines — there is no cross-machine case to
+ * protect here. A pre-existing but unparseable file, or a sibling field that
+ * does not match `{timestamp, host}` (including an empty/whitespace-only
+ * value) or that carries an unrecognized key, is dropped rather than carried
+ * forward (never preserve garbage into a freshly-written record) — the same
+ * `isValidSyncSuccessRecord` predicate readSyncLastSuccess uses.
+ *
+ * Lock acquisition is best-effort — a timeout (or any other failure) is
+ * swallowed, same as appendSyncFailure, since a failed success-log must never
+ * break the caller (Stop hook / SessionStart).
+ *
+ * @param {string} hypoDir
+ * @param {'pull'|'push'} op
+ */
+export function recordSyncSuccess(hypoDir, op) {
+  try {
+    const path = syncLastSuccessPath(hypoDir);
+    withFileLock(path, () => {
+      let current = {};
+      try {
+        if (existsSync(path)) {
+          const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+          if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            for (const k of ['pull', 'push']) {
+              if (isValidSyncSuccessRecord(parsed[k])) current[k] = parsed[k];
+            }
+          }
+        }
+      } catch {
+        // corrupt existing file: overwrite with a fresh object rather than
+        // carry the corruption forward.
+      }
+      current[op] = { timestamp: new Date().toISOString(), host: hostname() };
+      atomicWriteShared(path, JSON.stringify(current, null, 2) + '\n');
+    });
+  } catch {
+    // best-effort: lock timeout or write failure must never break the caller
+  }
+}
+
 // ── auto-project suggestion ────────────────────────────────────────
 // `.cache/project-suggestions.json` is a single JSON object:
 //   { "skips": [{cwd, declined_at, reason}], "cooldowns": {"<cwd>": "<iso>"} }
@@ -1960,11 +3000,11 @@ export function clearClearMarker(hypoDir) {
 // Writer authority lives in crystallize, NOT this hook: the hook only checks
 // presence. See amendment 2026-05-19 Q2 for the split rationale.
 
-const SESSION_CLOSED_MARKER_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+export const SESSION_CLOSED_MARKER_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 
 /** Sanitize session_id for filesystem use — Claude session_ids are UUIDs but
  *  defend against accidental path traversal regardless. */
-function sanitizeSessionId(sessionId) {
+export function sanitizeSessionId(sessionId) {
   return String(sessionId)
     .replace(/[^A-Za-z0-9._-]/g, '_')
     .slice(0, 128);
@@ -3120,6 +4160,118 @@ export function isClosePattern(text) {
   return [...krPatterns, ...enPatterns].some((re) => re.test(text));
 }
 
+// ── close ARTIFACTS, not the marker (issue: close gate lives on one writer) ──
+//
+// hasUserCloseSignal/isClosePattern answer "did the user ask to close" — the
+// input side of the gate. This answers a different question: "does this file
+// or commit message already READ as closed to a human", independent of
+// whether any marker writer ever ran. The 2026-07-28 incident produced a
+// closing session-state.md heading, a rewritten hot.md, and a close-worded
+// commit WITHOUT writing a session-closed marker at all — the hard gate on
+// the marker writer never fired because the model never called it. Closing
+// is a set of user-visible artifacts, not one internal file.
+//
+// Narrowed scope — this is a PARTIAL defense, not the completed artifact-set
+// gate: hot.md's REPLACEMENT is a diff against the prior version, which a
+// pure function taking only current content cannot see. This only catches a
+// hot.md that carries close vocabulary in its own bold heading — a hot.md
+// rewritten with a closing narrative that happens not to use 마감/종료
+// literally (as the incident's own hot.md rewrite did) will NOT trip this
+// signal. That is a real, known false-negative, not a corner this slice
+// closes: catching it needs a diff-aware check (comparing against the prior
+// committed hot.md, or a PreToolUse guard that sees the edit as it happens),
+// which is future work, not something reusing isClosePattern's heuristics
+// would fix either. The session-state heading and commit-message signals
+// still catch the one incident on record, so today's gap is documented, not
+// silent — but it is a gap, not a boundary this slice was designed to hold.
+//
+// A close word used as a NOUN-MODIFIER is not an announcement — "마감
+// 조건을/여부/로직/절차/정책" all describe something ABOUT closing, not a close
+// that happened. Enumerating the modifiers (blacklist, round 1) and then the
+// verb suffixes that ARE an announcement (whitelist, round 2) both kept
+// finding new words each review round — neither converges, because both are
+// open lexical classes. The convergent rule is a WORD-BOUNDARY, not a word
+// list: Korean verb conjugation attaches directly with no space (마감했다,
+// 마감되었습니다, 마감했습니다, 마감됨 — see the corpus in
+// tests/close-signals.test.mjs), while a noun-modifier is a SEPARATE word
+// after a space (마감 조건, 마감 정책, 종료 여부, 종료 절차). So: a close word
+// followed immediately (no space) by more Hangul is a conjugation and
+// announces a close; a close word followed by whitespace THEN Hangul is a
+// modifier and does not. `CLOSE_WORD_TAIL` consumes the (possibly empty)
+// directly-attached conjugation run, then requires the close word to be
+// effectively the LAST content in its heading: only a parenthetical, ":" +
+// trailing narrative, terminal punctuation, or the bold-heading's end may
+// follow — a bare space-separated Hangul word after it fails to match any of
+// those and rejects. Known accepted limit: a same-word-no-space compound like
+// "마감일" (deadline-date, a noun) would match — over the FN/FP asymmetry this
+// check is built on (a missed real close is the exact failure mode it exists
+// to catch; a stray warn is mild noise), that's the accepted direction.
+const CLOSE_WORD_TAIL = '[가-힣]*(?:\\s*:[^*\\n]*|(?:\\([^)]*\\))?[.,]?\\s*)';
+const SESSION_STATE_CLOSE_HEADING = new RegExp(
+  `\\*\\*(\\d{4}-\\d{2}-\\d{2})[^*\\n]*?마감${CLOSE_WORD_TAIL}\\*\\*`,
+);
+const HOT_CLOSE_NARRATIVE = new RegExp(
+  `\\*\\*(\\d{4}-\\d{2}-\\d{2})[^*\\n]*?(?:마감|세션\\s*종료)${CLOSE_WORD_TAIL}\\*\\*`,
+);
+// EN: requires the CLOSE's object to actually be "session" ("close the
+// session" / "close the Nth session" — an ORDINAL or digit-ordinal, the only
+// forms a real close commit uses), not any noun ("close the database
+// session", "close the browser session" are technical commits, not a
+// session-close). KR: same word-boundary rule as the heading patterns above,
+// applied as a lookahead only (a commit subject isn't bold-wrapped, so there
+// is no terminal structure to consume into) — reject only when a bare SPACE
+// separates the close word from a following Hangul word; a directly-attached
+// conjugation (세션을 종료했다) still matches. "을/를" is the object particle
+// Korean puts between "세션" and its verb.
+const ORDINAL =
+  '(?:\\d+(?:st|nd|rd|th)|first|second|third|fourth|fifth|sixth|seventh|eighth|ninth|tenth|' +
+  'eleventh|twelfth|thirteenth|fourteenth|fifteenth|sixteenth|seventeenth|eighteenth|nineteenth|twentieth)';
+const CLOSE_COMMIT_MESSAGE = new RegExp(
+  `\\b(?:session:\\s*)?close(?:s|d)?\\s+(?:the|this)\\s+(?:${ORDINAL}\\s+)?session\\b|` +
+    `세션(?:을|를)?\\s*(?:마무리|마감|종료)(?!\\s+[가-힣])`,
+  'i',
+);
+
+/**
+ * Pure predicate: is this file content, or this commit message, a
+ * session-close ARTIFACT (something a human would read as "this session was
+ * closed")? Never reads the filesystem — callers own IO. `path`'s basename
+ * selects which pattern applies (`session-state.md` vs `hot.md`); pass
+ * `commitMessage` instead for a git log entry.
+ *
+ * Consumed today by doctor's post-hoc check: an artifact with no matching
+ * session-closed marker for its date is a signature of a hand-made close
+ * that never went through the gate. Meant to also back a future PreToolUse
+ * guard on the same definition, so the two defenses can't drift apart on
+ * what "close" means.
+ *
+ * @param {{path?: string|null, content?: string|null, commitMessage?: string|null}} input
+ * @returns {{matched: boolean, kind: string|null, date: string|null}} `date`
+ *   is the YYYY-MM-DD captured from the artifact's own heading, or null for a
+ *   commit-message match (the caller already has the commit's date).
+ */
+export function detectSessionCloseArtifact({
+  path = null,
+  content = null,
+  commitMessage = null,
+} = {}) {
+  if (typeof commitMessage === 'string' && CLOSE_COMMIT_MESSAGE.test(commitMessage)) {
+    return { matched: true, kind: 'commit-message', date: null };
+  }
+  if (typeof path === 'string' && typeof content === 'string') {
+    const base = path.split(/[\\/]/).pop();
+    if (base === 'session-state.md') {
+      const m = SESSION_STATE_CLOSE_HEADING.exec(content);
+      if (m) return { matched: true, kind: 'session-state-heading', date: m[1] };
+    }
+    if (base === 'hot.md') {
+      const m = HOT_CLOSE_NARRATIVE.exec(content);
+      if (m) return { matched: true, kind: 'hot-narrative', date: m[1] };
+    }
+  }
+  return { matched: false, kind: null, date: null };
+}
+
 /**
  * Resolve a session's transcript path from its (globally-unique) session id by
  * globbing every Claude project dir: ~/.claude/projects/<slug>/<id>.jsonl.
@@ -3181,6 +4333,9 @@ export function resolveTranscriptBySessionId(
  *   • INVALIDATE a fresh user intent that expires the lease: any other genuine
  *                user text, `/clear`, `popAll`, a non-close queued_command, a
  *                non-close AskUserQuestion selection.
+ *   • NEUTRAL    additionally: a typed `apply-proposals <nonce>` whose nonce this
+ *                transcript shows `proposal challenge` minting (see "the approval
+ *                line" below).
  *   • NEUTRAL    everything the model can produce or the harness injects: system/
  *                sdk replay, isMeta bodies, sidechain, interruptedMessageId
  *                companions, assistant, tool_result, task-notification.
@@ -3193,9 +4348,45 @@ export function resolveTranscriptBySessionId(
  * known limit (no leaf pointer exists to resolve it — see the branch note on the
  * function), mitigated by the lease.
  *
+ * THE APPROVAL LINE IS NOT A CHANGE OF MIND. The lease exists to catch a user who
+ * changed their mind, and it also caught the user for doing what the close
+ * procedure told them to do. `proposal challenge` instructs the user to type
+ * `apply-proposals <nonce>`, which can never be a close phrase, so typing it
+ * expired the close grant given a turn earlier (measured 2026-08-06: the close
+ * needed three approval round trips because of it). Two gates read one transcript
+ * under two rules, and passing one broke the other.
+ *
+ * So one carve-out: a user message that IS the approval line, for a nonce this
+ * transcript shows being minted, is NEUTRAL. It never grants; a lease that was not
+ * already live stays dead. The mint has to be correlated, not merely present:
+ * `collectMinted` reads only a tool_result correlated to a Bash tool_use, and only
+ * when the surrounding challenge framing is there too, so a hex the model typed in
+ * its own prose (or any other tool's output) is not a mint. Order is part of it:
+ * the set fills as the walk goes, so a message can never mint the nonce it spends.
+ * An unminted hex is ordinary text and still expires the lease.
+ *
+ * What this does NOT cover: an AskUserQuestion answer during the close procedure
+ * (the skill's Step 1a reflections) still expires the lease. A carve-out was
+ * written for it and withdrawn, because "the answer does not read as a retraction"
+ * is fail-open on an open class of phrasings, and this repo routes an unknown value
+ * to the cautious branch. Recognizing a close-procedure answer POSITIVELY needs a
+ * marker on the question, and the model authors the question. The round trip stays.
+ *
  * Threat model: an honest-but-drifting model that does not forge the
  * transcript. This is a safety interlock, not an authorization boundary — a model
- * that forges records is out of scope and documented so.
+ * that forges records is out of scope and documented so. The carve-out does not
+ * move that boundary: it only PRESERVES a grant the user already gave, so the model
+ * still cannot manufacture one. The residual it does carry: a model that runs an
+ * arbitrary Bash command can print the challenge framing itself and plant a mint.
+ * That buys it nothing on its own, because the user still has to send the approval
+ * line, and the result is neutrality rather than a grant.
+ *
+ * A command invocation is NOT a channel here. `/hypo:crystallize` typed by the user
+ * was accepted as a grant for one review round and removed: the harness records a
+ * model-issued Skill call as the same non-meta `<command-name>` user record
+ * (verified against Claude Code 2.1.243's `processPromptSlashCommand`), so the
+ * model could have closed the session by calling its own skill. The premise that a
+ * command tag proves a human typed it is false.
  *
  * Fail-closed: any read/parse error, or an unresolvable branch, → false.
  */
@@ -3292,9 +4483,42 @@ export function hasUserCloseSignal(transcriptPath) {
   // staleness limit, mitigated by the lease: any later live user intent, on any
   // branch, still expires it.
   const askIds = new Set();
+  // Bash tool_use ids, so a mint can be tied to a command that actually ran rather
+  // than to any string in the file. Filled in the same content scan as askIds.
+  const bashIds = new Set();
   let granted = false;
+  // The nonces this transcript shows `proposal challenge` minting. Producer, not
+  // just presence: the hex has to arrive in a NON-error tool_result of a Bash
+  // tool_use, wrapped in the challenge's own framing. Model prose carrying a
+  // plausible hex, an isMeta/system body, and any other tool's output all fail
+  // that, which matters because a mint neutralizes the user's next message. The
+  // set fills as the walk goes, so a message cannot mint the nonce it spends.
+  const mintedNonces = new Set();
+  const challengeMint = new RegExp(
+    `must type this line in the conversation:\\s*${APPROVAL_PHRASE} ([a-f0-9]{32,})\\s*Then run: hypomnema proposal resolve`,
+    'g',
+  );
+  const approvalLine = new RegExp(`^${APPROVAL_PHRASE}\\s+([a-f0-9]{32,})$`);
+  const collectMinted = (o) => {
+    const c = (o.message ?? o).content;
+    if (!Array.isArray(c)) return;
+    for (const b of c) {
+      if (!b || typeof b !== 'object') continue;
+      if (b.type !== 'tool_result' || !b.tool_use_id || !bashIds.has(b.tool_use_id)) continue;
+      if (b.is_error === true) continue;
+      const text = typeof b.content === 'string' ? b.content : JSON.stringify(b.content);
+      if (typeof text !== 'string' || !text.includes(APPROVAL_PHRASE)) continue;
+      for (const m of text.matchAll(challengeMint)) mintedNonces.add(m[1]);
+    }
+  };
 
   for (const o of recs) {
+    // Genuine user text of this record, or null when the record is on a channel
+    // the model can reach. Computed once here: the mint scan below is the exact
+    // complement of it (mint from everything that is NOT the user's own text).
+    const userText = eventUserText(o);
+    if (userText == null) collectMinted(o);
+
     // Queue operations. The queue carries no correlation key (measured), so the
     // ENQUEUE content is the decision — not a later contentless dequeue, which
     // would need pairing we cannot do. Reading the enqueue also keeps the live
@@ -3344,25 +4568,29 @@ export function hasUserCloseSignal(transcriptPath) {
     }
 
     // Record AskUserQuestion tool_use ids (assistant record, always precedes its
-    // answer in line order).
+    // answer in line order). Bash ids ride along in the same scan, for the mint
+    // correlation above.
     const content = (o.message ?? o).content;
     if (Array.isArray(content)) {
       for (const b of content) {
-        if (
-          b &&
-          typeof b === 'object' &&
-          b.type === 'tool_use' &&
-          b.name === 'AskUserQuestion' &&
-          b.id
-        )
-          askIds.add(b.id);
+        if (!b || typeof b !== 'object' || b.type !== 'tool_use' || !b.id) continue;
+        if (b.name === 'AskUserQuestion') askIds.add(b.id);
+        else if (b.name === 'Bash') bashIds.add(b.id);
       }
     }
 
-    // Genuine user text → grant on a close phrase, invalidate on anything else.
-    const text = eventUserText(o);
-    if (text != null && text !== '') {
-      granted = isClosePattern(text);
+    // Genuine user text → grant on a close phrase, invalidate on anything else,
+    // minus the one carve-out for what the product itself asked the user to send.
+    if (userText != null && userText !== '') {
+      const spend = approvalLine.exec(userText.trim());
+      if (spend && mintedNonces.has(spend[1])) {
+        // The approval line `proposal challenge` tells the user to type, bound to a
+        // nonce this transcript minted. Neutral, never a grant: an untouched
+        // `granted` that was false stays false. An unminted hex is ordinary text and
+        // falls through to the invalidating branch below.
+        continue;
+      }
+      granted = isClosePattern(userText);
       continue;
     }