hypomnema 1.6.2 → 1.7.1

package/hooks/hypo-shared.mjs

@@ -16,10 +16,16 @@ import {
   rmSync,
   readdirSync,
   realpathSync,
+  openSync,
+  unlinkSync,
+  renameSync,
+  linkSync,
 } from 'fs';
-import { join, relative, basename } from 'path';
+import { join, relative, basename, dirname, isAbsolute } from 'path';
 import { homedir, hostname, tmpdir } from 'os';
 import { spawnSync } from 'child_process';
+import { randomBytes } from 'crypto';
+import { fileURLToPath } from 'url';
 
 const HOME = homedir();
 
@@ -90,19 +96,196 @@ 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.
+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 hooks/'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.
+function selfLocationPkgRoot() {
+  let hooksDir, ownRealPath;
+  try {
+    hooksDir = dirname(fileURLToPath(import.meta.url));
+    ownRealPath = realpathSync(join(hooksDir, 'hypo-shared.mjs'));
+  } catch {
+    return null; // can't even resolve our own path — 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;
+  }
+}
+
+// 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 cache get to answer, and only
+// after passing the same usable-root contract as everything else here.
+function resolvePkgRoot() {
+  const self = selfLocationPkgRoot();
+  if (self) return self;
+  const cached = readCachedPkgRoot();
+  return isUsablePkgRootLocal(cached) ? cached : 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;
@@ -330,18 +513,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 /
@@ -418,7 +613,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
@@ -435,38 +634,96 @@ 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;
 }
@@ -525,7 +782,12 @@ function _lastSeg(p) {
 // declines (null) so the caller falls back to recency. `projects` is the whole
 // universe (for the uniqueness gate); `eligible` restricts the answer.
 export function pickProjectByCwd(projects, cwd, opts = {}) {
-  const { eligible = null, realpathCwd = null, caseInsensitive = isCaseInsensitiveFs() } = opts;
+  const {
+    eligible = null,
+    realpathCwd = null,
+    caseInsensitive = isCaseInsensitiveFs(),
+    rejectAmbiguous = false,
+  } = opts;
   if (!cwd && !realpathCwd) return null;
   const eligibleSet = eligible ? new Set(eligible) : null;
   const isEligible = (slug) => !eligibleSet || eligibleSet.has(slug);
@@ -545,20 +807,35 @@ export function pickProjectByCwd(projects, cwd, opts = {}) {
     if (n && !cwds.includes(n)) cwds.push(n);
   }
 
-  // Tier 1: first cwd variant with any longest-prefix match wins.
+  // Tier 1: first cwd variant with any longest-prefix match wins. With
+  // rejectAmbiguous (session-cwd close check), two DISTINCT projects sharing the same
+  // longest matching working_dir (a monorepo config with no uniqueness invariant)
+  // is a genuine tie we must NOT break arbitrarily — silently picking the first
+  // would attribute a close to the wrong project and either mask a real failure
+  // (false-green) or block the wrong one (false-block). Decline the tie → null,
+  // so the caller degrades to the unresolved-cwd path instead of guessing.
   for (const c of cwds) {
     const cf = _fold(c, caseInsensitive);
     let bestSlug = null;
     let bestLen = -1;
+    let bestTied = false;
     for (const e of entries) {
       if (!isEligible(e.slug)) continue;
       const pf = _fold(e.path, caseInsensitive);
-      if ((cf === pf || cf.startsWith(`${pf}/`)) && e.path.length > bestLen) {
-        bestLen = e.path.length;
-        bestSlug = e.slug;
+      if (cf === pf || cf.startsWith(`${pf}/`)) {
+        if (e.path.length > bestLen) {
+          bestLen = e.path.length;
+          bestSlug = e.slug;
+          bestTied = false;
+        } else if (e.path.length === bestLen && e.slug !== bestSlug) {
+          bestTied = true;
+        }
       }
     }
-    if (bestSlug) return bestSlug;
+    if (bestSlug) {
+      if (bestTied && rejectAmbiguous) return null;
+      return bestSlug;
+    }
   }
 
   // Tier 2: unique-basename ancestor, but only when the chain points at exactly
@@ -1130,7 +1407,10 @@ export function sessionCloseGlobalStatus(hypoDir, opts = {}) {
 
   // primary = the recency project when it is itself today-active, else the first
   // today-active slug (stable order from the candidate set). Used only as the
-  // single-slug alias (marker `project` field, message header) — never to gate.
+  // single-slug alias for the message header and the flat `close.project` field.
+  // It is NEVER an attribution source: the marker is stamped from close evidence
+  // (explicit --project, transcript close-files, apply's payload.project), so this
+  // recency-derived value cannot leak into a marker and back into the next gate.
   const primary = recency && todayActive.includes(recency) ? recency : todayActive[0];
   const ordered = [primary, ...todayActive.filter((p) => p !== primary)];
 
@@ -1203,6 +1483,267 @@ export function rootLogEntry(slug, date, headingTail) {
  * @param {string} hypoDir
  * @returns {number} count of entries appended to log.md
  */
+// ── append-only file lock ───────────────────────────────────────────────────
+// Serializes the read → dedup → rebuild → temp+rename sequence on append-only
+// history files (session-log shards, log.md) so two concurrent session closes
+// never lose an entry. The lock does NOT replace the existing write-isolation:
+// each writer still rebuilds the full content and commits via atomicWrite
+// (temp write + rename), so a partial write lands on a throwaway temp and the
+// target is never torn. The lock only makes the read-modify-write exclusive, so
+// the second closer re-reads the first's committed bytes and appends onto them
+// (last-writer-wins can no longer drop the earlier entry), and exact-entry dedup
+// becomes precise rather than best-effort.
+//
+// Why not O_APPEND: an in-place append that short-writes (ENOSPC / EDQUOT /
+// RLIMIT_FSIZE / a split write() killed mid-loop) leaves a torn dated heading on
+// the real file that the freshness gate mis-reads as valid close evidence, and
+// it cannot be rolled back once a concurrent appender has written past it. That
+// is a normal-operation regression temp+rename does not have (a failed temp
+// write never runs the rename, so the target stays untouched). Confirmed against
+// Node/libuv write-loop behavior and POSIX write(2) partial-write semantics.
+//
+// Local-FS only: `openSync(lock, 'wx')` is not atomic on NFS — the same caveat
+// the vault already carries. Power-loss durability is unchanged from today
+// (atomicWrite never fsync'd), so it is out of scope here.
+function sleepSync(ms) {
+  // Synchronous sleep with no busy-spin: block this thread on an Atomics.wait
+  // against a private SharedArrayBuffer that is never signaled, so it always
+  // times out after `ms`. Hooks run in a short-lived sync context.
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, ms | 0));
+}
+
+// Commit `content` via temp write + rename so a partial/failed write lands on a
+// throwaway temp and the target is never torn (mirrors crystallize.mjs's
+// atomicWrite). Rename atomicity swaps the directory entry; it is NOT power-loss
+// durable (no fsync) — same as everything else in the vault.
+function atomicWriteShared(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+// Read 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 `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
+ * @param {{timeoutMs?: number, staleMs?: number, pollMs?: number}} [opts]
+ * @returns {T} whatever `fn` returns
+ * @template T
+ */
+export function withFileLock(targetPath, fn, opts = {}) {
+  const { timeoutMs = 5000, staleMs = 30000, pollMs = 50 } = opts;
+  const lockPath = `${targetPath}.lock`;
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const start = Date.now();
+  // 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 {
+      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 {
+        // 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);
+    }
+  }
+  } 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 {
+      unlinkSync(tmpPath);
+    } catch {
+      /* 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 {
+      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 */
+    }
+  }
+}
+
 export function deriveRootLogEntries(hypoDir) {
   const logPath = join(hypoDir, 'log.md');
   if (!existsSync(logPath)) return 0;
@@ -1259,19 +1800,44 @@ export function deriveRootLogEntries(hypoDir) {
         const { heading, block } = rootLogEntry(slug, date, m[1]);
         if (seenHeadings.has(heading)) continue; // exact-line dedup (log.md + queued)
         seenHeadings.add(heading);
-        additions.push(block);
+        additions.push({ heading, block });
       }
     }
   }
 
   if (additions.length === 0) return 0;
-  const sep = logContent.endsWith('\n') ? '\n' : '\n\n';
+
+  // Serialize the read-modify-write on log.md: a concurrent session close (its
+  // own crystallize apply, or another project's derive) may commit between the
+  // read above and the write below. Under the lock we RE-READ the latest
+  // committed log.md and re-run exact-heading dedup, so this derive appends onto
+  // the other writer's entry instead of a full-file overwrite dropping it. The
+  // same lock guards crystallize.mjs's per-close log.md append, so the two
+  // paths never race. On lock-timeout, skip (best-effort backfill; the next
+  // close re-derives) rather than risk a lost update.
   try {
-    writeFileSync(logPath, logContent + sep + additions.join('\n\n') + '\n');
+    return withFileLock(logPath, () => {
+      let current;
+      try {
+        current = readFileSync(logPath, 'utf-8');
+      } catch {
+        return 0;
+      }
+      const seen = new Set((current || '').split(/\r?\n/));
+      const fresh = additions.filter(({ heading }) => {
+        if (seen.has(heading)) return false;
+        seen.add(heading);
+        return true;
+      });
+      if (fresh.length === 0) return 0;
+      const sep = current.endsWith('\n') ? '\n' : '\n\n';
+      atomicWriteShared(logPath, current + sep + fresh.map((a) => a.block).join('\n\n') + '\n');
+      return fresh.length;
+    });
   } catch {
+    // lock-timeout or unexpected lock error: skip this backfill pass.
     return 0;
   }
-  return additions.length;
 }
 
 // ── sync-state ────────────────────────────────────────────
@@ -1285,6 +1851,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.
@@ -1349,6 +1948,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.
@@ -1373,67 +1973,480 @@ 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');
+}
+
+/**
+ * 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 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
+ * 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}` };
-  const porcelain = git('status', '--porcelain', '-uall');
+
+  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
+  // `"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 porcelain = git('status', '--porcelain', '-uall', '-z');
   if (porcelain.status !== 0)
     return { committed: false, reason: `git status failed in ${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 = [];
-  for (const line of (porcelain.stdout || '').split('\n')) {
-    if (!line) continue;
-    const file = line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop().trim();
+  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.
+    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 };
 }
 
 /**
@@ -1464,6 +2477,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>"} }
@@ -1763,11 +2904,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);
@@ -1799,9 +2940,22 @@ export function writeSessionClosedMarker(hypoDir, sessionId, info = {}) {
     // attribution). Readers (precompactGateStatus / --check-session-close) key
     // the gate semantics on this field, so it must be recorded.
     const scope = info.scope === 'log-only' ? 'log-only' : 'project';
+    // v4 attribution discriminator (session-close attribution). `projects` is the evidence-based
+    // set this session actually closed — explicit --project ∪ transcript
+    // close-file edits ∪ apply's authoritative payload.project — and NEVER the
+    // recency primary. Its PRESENCE marks a v4 marker whose scope resolveCloseScope
+    // trusts directly; a pre-v4 marker carries only `project` and is treated as an
+    // uncorroborated legacy hint (see resolveCloseScope). `project` stays as
+    // projects[0] for back-compat with the flat-field readers.
+    const projects = Array.isArray(info.projects)
+      ? [...new Set(info.projects.filter(Boolean))]
+      : info.project
+        ? [info.project]
+        : [];
     const payload = {
       session_id: sessionId,
-      project: info.project || null,
+      project: info.project || projects[0] || null,
+      projects,
       scope,
       transcript_path: info.transcript_path || null,
       closed_at: new Date().toISOString(),
@@ -2170,6 +3324,64 @@ export function isUnderProjectDirs(file, slugs) {
   return (slugs || []).some((s) => s && (f === `projects/${s}` || f.startsWith(`projects/${s}/`)));
 }
 
+/**
+ * The session-close FILES of some project, as a path matcher. Used to attribute a
+ * close to a session: a transcript that edited `projects/<slug>/session-state.md`
+ * (or that project's hot.md / a session-log shard) is evidence THIS session was
+ * closing <slug>. Any other file under `projects/<slug>/` is NOT evidence — merely
+ * editing a page or an ADR there says nothing about whose close is whose, and
+ * treating it as attribution would re-block a session for a project it only read
+ * around in (codex design review).
+ */
+const CLOSE_FILE_RE = /^projects\/([^/]+)\/(session-state\.md|hot\.md|session-log\/[^/]+\.md)$/;
+
+/** Slugs whose close files this session edited directly (Write/Edit tool_use). */
+function projectsFromTouchedCloseFiles(transcriptPath, hypoDir) {
+  const out = new Set();
+  if (!transcriptPath) return out;
+  for (const f of extractTouchedWikiFiles(transcriptPath, hypoDir)) {
+    const m = posixPath(f).match(CLOSE_FILE_RE);
+    if (m) out.add(m[1]);
+  }
+  return out;
+}
+
+/**
+ * closeScope: the projects THIS session is accountable for closing. The union of
+ * three signals, because no single one covers every close path:
+ *
+ *   1. `opts.closeScope` — the caller states it outright. `--apply-session-close`
+ *      passes `payload.project` (it is the authority on what it just closed) and
+ *      `--mark-session-closed --project=<slug>` passes its attribution slug. This
+ *      signal is LOAD-BEARING, not a convenience: the documented close path writes
+ *      its files from inside a Bash call, so they never surface as Edit/Write
+ *      `file_path`s and signal 2 cannot see them (the same blind spot that forces
+ *      closeFileTargets() to seed the lint scope explicitly).
+ *   2. close files the transcript shows this session editing — the hand-written
+ *      close, which bypasses the script entirely.
+ *   3. `marker.project` — after a scripted close marked, this is how a later reader
+ *      (PreCompact) recovers signal 1. It is what keeps the marker == compact-ready
+ *      invariant: the writer scopes by `payload.project`, PreCompact re-scopes by
+ *      the `project` that same writer recorded, so the two can never disagree.
+ */
+export function resolveCloseScope(hypoDir, opts = {}, marker = null) {
+  const scope = new Set(opts.closeScope || []);
+  for (const p of projectsFromTouchedCloseFiles(opts.transcriptPath, hypoDir)) scope.add(p);
+  // Marker attribution (session-close attribution). A v4 marker carries `projects` — the
+  // evidence-based set it closed (never recency) — trusted directly. A pre-v4
+  // legacy marker carries only `project` with no provenance, and that value may be
+  // recency-derived (the P1 bug). An uncorroborated legacy attribution must NOT
+  // enable partitioning, or a stale/wrong slug could demote a real failure to
+  // foreign debt. So a legacy `project` enters scope only when the direct signals
+  // above (explicit close scope or transcript close-file edits) already corroborate
+  // the SAME slug; otherwise it stays a display hint. This narrow gap self-heals as
+  // pre-v4 markers expire (7-day TTL).
+  if (Array.isArray(marker?.projects)) {
+    for (const p of marker.projects) if (p) scope.add(p);
+  }
+  return scope;
+}
+
 // ── PreCompact gate — single source of truth ────────────────────────────────
 /**
  * The full PreCompact gate decision as a READ-ONLY status. This is the single
@@ -2201,7 +3413,15 @@ export function isUnderProjectDirs(file, slugs) {
  * ignored.
  *
  * @param {string} hypoDir
- * @param {{lintScope?: Iterable<string>, transcriptPath?: string|null, claudeHome?: string, projectOverride?: string|null}} [opts]
+ * opts.sessionCwd (session-cwd close check): the authoritative cwd of the session being
+ * gated (hook payload.cwd, or the CLI --session-cwd flag — never process.cwd(),
+ * which is post-`cd` non-authoritative). When set and not log-only, the project
+ * that owns this cwd is checked for close-completeness as an INDEPENDENT blocker,
+ * catching a session whose own project close was never started. Unmatched/ambiguous
+ * cwd yields a best-effort notice, not a block. apply never passes it (its launch
+ * cwd may differ from the authoritative payload.project).
+ *
+ * @param {{lintScope?: Iterable<string>, transcriptPath?: string|null, claudeHome?: string, projectOverride?: string|null, sessionCwd?: string|null, sessionId?: string|null, logOnly?: boolean, closeScope?: string[]}} [opts]
  * @returns {{ok: boolean, close: object, blockers: {type:string,reason:string}[], notices: {type:string,reason:string,file?:string}[], driftTargets: string[], skipped: {lint:boolean, feedback:boolean}}}
  */
 export function precompactGateStatus(hypoDir, opts = {}) {
@@ -2267,6 +3487,72 @@ export function precompactGateStatus(hypoDir, opts = {}) {
     // projectOverride narrows the close status to one project (check-only); a
     // marker-writing caller never sets it, so the marker path stays global.
     close = sessionCloseGlobalStatus(hypoDir, { projectOverride: opts.projectOverride });
+
+    // Attribute the close debt before blocking on it. An incomplete close belongs
+    // to whichever session performed it; charging it to an unrelated session is the
+    // false block this partition exists to stop. The gate already draws exactly this
+    // line for LINT debt (partitionLintScope: errors in files THIS session touched
+    // block, pre-existing debt elsewhere is a notice) — close-file debt was the one
+    // check still hard-blocking globally on another session's work.
+    //
+    // Two fail-closed guards keep the partition from eating a real blocker:
+    //   - close.fallback: no project closed today, so this is the "you have not
+    //     closed this session AT ALL" path. It must block unconditionally; demoting
+    //     it would gut the gate's whole purpose.
+    //   - empty scope: no positive attribution signal, so we cannot tell whose debt
+    //     it is. Never demote on a guess — fall back to today's global block.
+    //   - projectOverride: the caller asked "is THIS project close-complete?".
+    //     Demoting the very project it named would answer a question nobody asked.
+    //
+    // Bounded tradeoff (codex design review, accepted rather than closed). A
+    // scripted close that CRASHES mid-write leaves no marker and no transcript trace
+    // (it writes from inside a Bash call), so its own project carries no attribution.
+    // If that same session had also hand-edited SOME OTHER project's close files, the
+    // scope is non-empty but omits the torn project, and its debt is demoted. The
+    // window is narrow and self-limiting: apply writes the project files, then the
+    // session-log, then the root log entry, so the only torn state that reaches this
+    // partition at all is a missing log.md entry — which deriveRootLogEntries
+    // regenerates from the session-log heading. A crash before the session-log is not
+    // detected as today-active by hasTodayCloseActivity in the first place (the
+    // pre-existing tradeoff documented there). And the marker is never written, so the
+    // Stop hook still refuses to end the session. Closing this properly needs a
+    // durable close-attempt record; it is not worth a new state-file lifecycle here.
+    const scopeSet = resolveCloseScope(hypoDir, opts, marker);
+    const failed = (close.projects || []).filter((p) => !p.ok);
+    const partition =
+      !close.fallback && !opts.projectOverride && scopeSet.size > 0 && failed.length > 0;
+
+    close.scope = [...scopeSet];
+    close.debt = [];
+    // Re-project the flat aliases onto what actually BLOCKS, so `ok` and
+    // `stale`/`missing` can never contradict each other (a reader that treats a
+    // non-empty `missing` as failure stays correct). Demoted debt moves to its own
+    // `debt` field instead of masquerading as this session's unfinished work.
+    //
+    // ONLY when partitioning. Deriving `ok` from the per-project rows unconditionally
+    // would silently drop the failures that have NO project row to be derived from:
+    // an unresolvable active project yields `projects: []` with
+    // `missing: ['hot.md (no active project in pointer table)']`, so an empty `failed`
+    // would read as "nothing failed" and flip a red gate green (codex pre-commit
+    // BLOCKER, reproduced on a vault with no active-project row). Outside the
+    // partition the close status stands exactly as sessionCloseGlobalStatus computed it.
+    if (partition) {
+      const mine = failed.filter((p) => scopeSet.has(p.project));
+      const foreign = failed.filter((p) => !scopeSet.has(p.project));
+      close.debt = foreign.map((p) => ({ project: p.project, stale: p.stale, missing: p.missing }));
+      close.stale = [...new Set(mine.flatMap((p) => p.stale))];
+      close.missing = [...new Set(mine.flatMap((p) => p.missing))];
+      close.ok = mine.length === 0;
+      // The flat `project` alias must follow the scope too: it names the project the
+      // rest of this status describes, and every consumer that renders a per-file
+      // checklist builds it from that name. Left as the global `primary` it can point
+      // at a DEMOTED foreign project, and the checklist then reports ✓ for files the
+      // debt list simultaneously calls missing (codex pre-commit CONCERN).
+      if (!scopeSet.has(close.project)) {
+        close.project = mine[0]?.project ?? [...scopeSet][0] ?? close.project;
+      }
+    }
+
     if (!close.ok) {
       blockers.push({
         type: 'close',
@@ -2276,6 +3562,74 @@ export function precompactGateStatus(hypoDir, opts = {}) {
         ].join(', ')}`,
       });
     }
+    for (const p of close.debt) {
+      notices.push({
+        type: 'close-debt',
+        project: p.project,
+        reason: `${p.project}: incomplete session close from another session (${[
+          ...p.missing.map((f) => `${f} (missing)`),
+          ...p.stale.map((f) => `${f} (stale)`),
+        ].join(', ')}) — not blocking; that project's next close will fix it`,
+      });
+    }
+  }
+
+  // 3b. session-cwd close (session-cwd close check). The current session's cwd project is an
+  // INDEPENDENT close responsibility. sessionCloseGlobalStatus above only sees
+  // projects that left an authoritative close-activity trace (a session-log
+  // heading / log.md entry), so a project whose close was NEVER STARTED is
+  // invisible — and if the recency project was closed the same day, the gate would
+  // go green while this session's real project stays unclosed (the false-green this
+  // closes). Evaluate it here, AFTER the partition and OUTSIDE scopeSet /
+  // close.projects, so it can neither be demoted to foreign debt (partition) nor
+  // spawn a W8 design-history blocker (which derives from close.projects). log-only
+  // sessions are exempt (no project to close). apply never passes sessionCwd (its
+  // launch cwd may differ from the authoritative payload.project — a supported
+  // cross-project close), so this runs only on the read / mark paths.
+  if (!logOnly && opts.sessionCwd) {
+    const cwdProject = pickProjectByCwd(collectProjectWorkingDirs(hypoDir), opts.sessionCwd, {
+      rejectAmbiguous: true,
+    });
+    if (cwdProject) {
+      const s = sessionCloseFileStatus(hypoDir, { projectOverride: cwdProject });
+      if (!s.ok) {
+        // ALWAYS emit the typed close-cwd blocker when the cwd project's close is
+        // incomplete — never suppress it as a duplicate of the global `close`
+        // blocker. The Stop hook keys its marker re-check on this exact type, so
+        // hiding it (even when a `close` blocker names the same project) would let
+        // Stop honor a stale marker and end the session green (codex pre-commit
+        // BLOCKER). A second entry for the same slug is merely noisy, never wrong.
+        blockers.push({
+          type: 'close-cwd',
+          project: cwdProject,
+          reason: `session cwd project '${cwdProject}' has an incomplete session close: ${[
+            ...s.missing.map((f) => `${f} (missing)`),
+            ...s.stale.map((f) => `${f} (stale)`),
+          ].join(', ')}`,
+        });
+        // If the partition demoted this project to foreign debt, it is NOT another
+        // session's work — it is THIS session's, and we just BLOCKED on it. Remove
+        // it from BOTH the debt notice and close.debt so the status cannot report
+        // the same project as non-blocking debt and a blocker at once (codex
+        // pre-commit CONCERN: crystallize renders close_debt from close.debt).
+        for (let i = notices.length - 1; i >= 0; i--) {
+          if (notices[i].type === 'close-debt' && notices[i].project === cwdProject)
+            notices.splice(i, 1);
+        }
+        if (Array.isArray(close.debt))
+          close.debt = close.debt.filter((d) => d.project !== cwdProject);
+      }
+    } else {
+      // cwd is under no project working_dir, or ambiguously under several (a
+      // monorepo tie pickProjectByCwd declined): we cannot attribute a close
+      // responsibility, so we do NOT hard-block (nothing proves there is anything
+      // to close). Surface a best-effort notice so the coverage gap is visible.
+      notices.push({
+        type: 'close-cwd-unresolved',
+        reason:
+          'session cwd did not resolve to a unique project — the P2 cwd close check is best-effort here; pass --project or --log-only to be explicit',
+      });
+    }
   }
 
   // 4. lint blockers + W8 design-history (scoped). Mirrors hypo-personal-check.
@@ -2425,8 +3779,55 @@ export function precompactGateStatus(hypoDir, opts = {}) {
           .map(([n]) => n);
         const overCapT = entries.filter(([, t]) => t.overCap).map(([n]) => n);
         const driftedT = entries.filter(([, t]) => t.dirty).map(([n]) => n);
-        if (!report || !(conflictedT.length || overCapT.length || driftedT.length)) {
-          skipped.feedback = true; // buildError / unparseable / non-actionable → fail-open
+        // A target whose file EXISTS but cannot be projected into (its
+        // <learned_behaviors> container is gone) reports dirty:false with no
+        // conflict flag — it cannot be built, so nothing "would change". That
+        // shape used to fall into the non-actionable branch below and fail OPEN,
+        // the worst possible reading: a projection that loads ZERO rules on this
+        // machine was classified as "nothing to do" and waved through. It is a
+        // blocker, not a shrug.
+        //
+        // ONLY kind 'build-failed'. A 'target-missing' buildError (no ~/.claude/
+        // CLAUDE.md yet) is the ordinary first-run state and must keep failing
+        // OPEN, or the gate blocks every new user on their first /compact.
+        const buildErrT = entries
+          .filter(([, t]) => t.buildError && t.buildErrorKind === 'build-failed')
+          .map(([n]) => n);
+        // Side-file I/O trouble (an unreadable feedback_<slug>.md under the
+        // project memory dir) is a NOTICE, never a blocker: the primary
+        // projection still loads every rule, and the only fix is a permission
+        // bit on that path — `--ensure-container` cannot touch it. A gate that
+        // blocks on a condition its own named remedy cannot clear is a gate that
+        // gets bypassed.
+        const sideWarnT = entries.filter(([, t]) => (t.sideWarnings || []).length);
+        if (
+          !report ||
+          !(
+            conflictedT.length ||
+            overCapT.length ||
+            driftedT.length ||
+            buildErrT.length ||
+            sideWarnT.length
+          )
+        ) {
+          skipped.feedback = true; // unparseable / non-actionable → fail-open
+        } else if (buildErrT.length) {
+          // Name the EXACT target file and the remedy for THIS cause. "Restore
+          // the managed container" with no path is a dead end, and so is naming
+          // `--ensure-container` for a permission error or a dangling symlink,
+          // which it cannot fix — a blocker with no way through gets bypassed
+          // rather than obeyed. t.buildError carries the target's absolute path
+          // and t.buildErrorRemedy the cause-specific way out; feedback-sync
+          // makes that judgment once, at the branch that detects the cause.
+          const failed = entries.filter(([n]) => buildErrT.includes(n));
+          const details = failed.map(([n, t]) => `${n}: ${t.buildError}`).join('; ');
+          const remedies = [
+            ...new Set(failed.map(([, t]) => t.buildErrorRemedy).filter(Boolean)),
+          ].join(' ');
+          blockers.push({
+            type: 'feedback',
+            reason: `feedback projection cannot be built — ${details} — no rules are loaded from it. ${remedies}`,
+          });
         } else if (conflictedT.length) {
           blockers.push({
             type: 'feedback',
@@ -2437,13 +3838,23 @@ export function precompactGateStatus(hypoDir, opts = {}) {
             type: 'feedback',
             reason: `feedback projection over cap (${overCapT.join(', ')}) — demote/archive feedback pages`,
           });
-        } else {
+        } else if (driftedT.length) {
           driftTargets.push(...driftedT); // pure drift → self-healable, not a blocker
           notices.push({
             type: 'feedback',
             reason: `feedback projection drift (${driftedT.join(', ')}) — will self-heal at /compact`,
           });
         }
+        // Additive, and deliberately outside the chain above: a side-file I/O
+        // problem is orthogonal to the primary target's health, so it is a notice
+        // whatever else is (or is not) going on. It names the path and the
+        // permission fix, because that — not a command — is the way out.
+        for (const [n, t] of sideWarnT) {
+          notices.push({
+            type: 'feedback',
+            reason: `feedback projection side file unreadable (${n}): ${t.sideWarnings.join('; ')} — fix the permissions on that path; the primary projection still loads every rule (\`--ensure-container\` does not fix this)`,
+          });
+        }
       }
     } catch {
       skipped.feedback = true;
@@ -2516,6 +3927,29 @@ export function isCompactOrClearCommand(prompt) {
  * @returns {string} newline-joined user text, or '' on any failure (fail-open)
  */
 export function extractUserMessages(transcriptPath, tailN = 30) {
+  return extractUserMessageRecords(transcriptPath, tailN, { keepEmpty: true }).join('\n');
+}
+
+/**
+ * Same extraction as {@link extractUserMessages}, but ONE STRING PER TRANSCRIPT
+ * RECORD instead of one flat blob. The message boundary is the point: a gate that
+ * asks "did the user say exactly X" cannot ask it of text that has been joined
+ * across turns, because any line of any message then looks like a whole message.
+ * {@link hasTypedUserApproval} needs that boundary; the close-intent readers, which
+ * only ever ask "does this text contain a close phrase", do not.
+ *
+ * @param {string} transcriptPath
+ * @param {number} tailN  how many trailing lines to scan (Infinity → whole file)
+ * @param {{keepEmpty?: boolean}} [opts]  keepEmpty preserves a '' per dropped record,
+ *   so the joined form stays byte-identical to what extractUserMessages always returned.
+ * @returns {string[]} user-typed text per record, or [] on any failure (fail-open)
+ */
+export function extractUserMessageRecords(transcriptPath, tailN = 30, { keepEmpty } = {}) {
+  const records = extractUserRecordTexts(transcriptPath, tailN);
+  return keepEmpty ? records : records.filter((t) => t !== '');
+}
+
+function extractUserRecordTexts(transcriptPath, tailN) {
   try {
     const lines = readFileSync(transcriptPath, 'utf-8').split('\n');
     // tailN === Infinity → whole transcript (the marker-write hard gate needs the
@@ -2523,51 +3957,49 @@ export function extractUserMessages(transcriptPath, tailN = 30) {
     // checklist). The Stop hook keeps the 30-line default so a stale old close
     // signal doesn't re-trigger every turn.
     const tail = Number.isFinite(tailN) ? lines.slice(-tailN) : lines;
-    return tail
-      .map((line) => {
-        try {
-          const obj = JSON.parse(line);
-          // Skill-injection vector: drop system-injected role:user
-          // messages before they pollute the close-intent signal.
-          //  • isMeta:true   — slash-command bodies, skill bodies, local-command
-          //    caveats. Their text is docs/specs, often full of close vocabulary
-          //    (e.g. the /hypo:crystallize spec literally contains close phrases),
-          //    which would let the gate self-satisfy the moment the model invokes
-          //    a close command. Confirmed isMeta:true in the transcript.
-          //  • promptSource system|sdk — task-notifications (system) and
-          //    SDK / QA-harness synthetic prompts (sdk). Neither is user-typed.
-          if (obj.isMeta === true) return '';
-          if (obj.promptSource === 'system' || obj.promptSource === 'sdk') return '';
-          const msg = obj.message ?? obj;
-          const role = msg.role ?? obj.role ?? obj.type;
-          if (role !== 'user') return '';
-          const content = msg.content ?? obj.content;
-          if (typeof content === 'string') {
-            // Stop-hook block feedback is recorded as a role:user string. It is
-            // the hook's OWN nudge ("[WIKI_AUTOCLOSE] … Run crystallize …"), not
-            // user intent — counting it would be circular (the hook that prods the
-            // model to close would become proof the user wanted to close).
-            return content.startsWith('Stop hook feedback') ? '' : content;
-          }
-          if (Array.isArray(content)) {
-            // Only genuine user-typed text blocks. tool_result blocks are also
-            // recorded with role:'user' in the Claude Code transcript; slurping
-            // them via JSON.stringify let tool output (e.g. close-pattern example
-            // strings read out of code/docs) trip the close-intent gate.
-            // Do NOT recurse into tool_result.content, or the pollution returns.
-            return content
-              .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
-              .map((b) => b.text)
-              .join('\n');
-          }
-          return '';
-        } catch {
-          return '';
+    return tail.map((line) => {
+      try {
+        const obj = JSON.parse(line);
+        // Skill-injection vector: drop system-injected role:user
+        // messages before they pollute the close-intent signal.
+        //  • isMeta:true   — slash-command bodies, skill bodies, local-command
+        //    caveats. Their text is docs/specs, often full of close vocabulary
+        //    (e.g. the /hypo:crystallize spec literally contains close phrases),
+        //    which would let the gate self-satisfy the moment the model invokes
+        //    a close command. Confirmed isMeta:true in the transcript.
+        //  • promptSource system|sdk — task-notifications (system) and
+        //    SDK / QA-harness synthetic prompts (sdk). Neither is user-typed.
+        if (obj.isMeta === true) return '';
+        if (obj.promptSource === 'system' || obj.promptSource === 'sdk') return '';
+        const msg = obj.message ?? obj;
+        const role = msg.role ?? obj.role ?? obj.type;
+        if (role !== 'user') return '';
+        const content = msg.content ?? obj.content;
+        if (typeof content === 'string') {
+          // Stop-hook block feedback is recorded as a role:user string. It is
+          // the hook's OWN nudge ("[WIKI_AUTOCLOSE] … Run crystallize …"), not
+          // user intent — counting it would be circular (the hook that prods the
+          // model to close would become proof the user wanted to close).
+          return content.startsWith('Stop hook feedback') ? '' : content;
         }
-      })
-      .join('\n');
+        if (Array.isArray(content)) {
+          // Only genuine user-typed text blocks. tool_result blocks are also
+          // recorded with role:'user' in the Claude Code transcript; slurping
+          // them via JSON.stringify let tool output (e.g. close-pattern example
+          // strings read out of code/docs) trip the close-intent gate.
+          // Do NOT recurse into tool_result.content, or the pollution returns.
+          return content
+            .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+        }
+        return '';
+      } catch {
+        return '';
+      }
+    });
   } catch {
-    return '';
+    return [];
   }
 }
 
@@ -2632,6 +4064,114 @@ 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.
@@ -2678,83 +4218,371 @@ export function resolveTranscriptBySessionId(
 }
 
 /**
- * Returns true iff the transcript carries a genuine USER session-close signal —
- * the hard gate for the session-closed marker writers. Scans the FULL
- * transcript: a close request can precede the marker write by the entire close
- * checklist, so the Stop hook's 30-line tail would miss it.
+ * Returns true iff the transcript's LATEST live user decision is to close — the
+ * hard gate for the session-closed marker writers. This is a state predicate, not
+ * an existence one: "is close still approved right now", not "did a
+ * close signal ever appear". Scans the FULL transcript in line order, classifies
+ * each record, and tracks the approval as a LEASE.
+ *
+ * Classification (structural fields only — never content heuristics for producer):
+ *   • GRANT      a genuine user close: an NL close phrase in user text that
+ *                survives {@link eventUserText}'s exclusions; a `/compact`
+ *                queue-op; a remove-path queued_command attachment carrying a
+ *                close with an audited human producer (origin.kind "human"); a
+ *                correlated, non-error AskUserQuestion answer naming a close.
+ *   • 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.
+ *   • FATAL      an unparseable line — the transcript is being appended to or is
+ *                corrupt, so refuse rather than read a half-written record.
+ *
+ * The last grant wins and a later invalidate expires it, so a stale close (Defect
+ * B), a queued "keep working" after a close, and a non-close AskUserQuestion
+ * selection all correctly read as NOT closed. Abandoned-branch staleness is a
+ * 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.
  *
- * Evidence (any one is sufficient):
- *   1. a de-polluted NL close phrase — isClosePattern over extractUserMessages,
- *      which already drops injected / tool / hook-feedback text;
- *   2. a `/compact` invocation (queue-operation). `/clear` is deliberately NOT
- *      counted: it abandons context, whereas a session-close PRESERVES the work
- *      to the wiki — a different intent;
- *   3. an AskUserQuestion answer whose SELECTED value names a close action (the
- *      canonical "offer [세션 마무리] → user picks it" flow).
+ * 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.
  *
- * A Stop-hook block is NOT evidence: it is the hook's own nudge to close, so
- * counting it would be circular (the incident's block told the model to write the
- * marker). extractUserMessages already strips it.
+ * 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.
  *
- * Fail-closed: any read error → false (caller refuses the marker).
+ * 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. 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.
  */
+// Genuine user text of a record, or null when the record is on a channel the
+// honest-but-drifting model can reach (so it is never user intent — NEUTRAL).
+// role:user is the boundary the model cannot cross: it authors role:assistant,
+// so a user record that survives every exclusion below is genuine user text.
+// The exclusions are exactly the model-reachable channels:
+//   • isMeta            slash-command / skill bodies and local-command caveats
+//   • promptSource system|sdk   queue replay of injected text, SDK prompts
+//   • isSidechain       subagent context (a subagent must not close the session)
+//   • interruptedMessageId  the harness cut the model off; user-SHAPED, not a
+//                       user decision (e.g. the [Request interrupted by user]
+//                       companion of a delivered /compact)
+//   • Stop-hook feedback  the hook's own close nudge — circular
+//   • tool_result blocks  tool output, not typed text
+// No promptSource allowlist is required: requiring `typed` would drop the
+// legacy absent-promptSource close the older gate has always honoured, while the
+// dangerous replay/injection paths carry system|sdk|isMeta|isSidechain and are
+// excluded here anyway.
+function eventUserText(obj) {
+  if (obj.isMeta === true) return null;
+  if (obj.promptSource === 'system' || obj.promptSource === 'sdk') return null;
+  if (obj.isSidechain === true) return null;
+  if (obj.interruptedMessageId) return null;
+  const msg = obj.message ?? obj;
+  const role = msg.role ?? obj.role ?? obj.type;
+  if (role !== 'user') return null;
+  const content = msg.content ?? obj.content;
+  if (typeof content === 'string') {
+    return content.startsWith('Stop hook feedback') ? null : content;
+  }
+  if (Array.isArray(content)) {
+    const texts = content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text);
+    return texts.length ? texts.join('\n') : null;
+  }
+  return null;
+}
+
+// A record on a channel the honest-but-drifting model can reach, so it can never
+// be a user decision. Used to keep injected / replayed / subagent records out of
+// BOTH the user-text and the AskUserQuestion-answer classifiers.
+function isModelReachableRecord(obj) {
+  return (
+    obj.isMeta === true ||
+    obj.promptSource === 'system' ||
+    obj.promptSource === 'sdk' ||
+    obj.isSidechain === true
+  );
+}
+
 export function hasUserCloseSignal(transcriptPath) {
   if (!transcriptPath) return false;
-  let lines;
+  let raw;
   try {
-    lines = readFileSync(transcriptPath, 'utf-8').split('\n');
+    raw = readFileSync(transcriptPath, 'utf-8');
   } catch {
     return false;
   }
-  // (1) NL close over the full, de-polluted transcript.
-  if (isClosePattern(extractUserMessages(transcriptPath, Infinity))) return true;
-  // AskUserQuestion answers (3) must be correlated to a real AskUserQuestion
-  // tool_use by id — otherwise ANY tool_result string containing "have been
-  // answered" (e.g. a Read/Grep of this very file, or of a transcript) would
-  // satisfy the gate, reintroducing the tool_result pollution the de-pollution
-  // layer closes. First pass collects the genuine AskUserQuestion tool_use ids;
-  // the tool_use (assistant) always precedes its tool_result (user) in the log,
-  // so a single forward scan suffices.
-  const askIds = new Set();
-  for (const line of lines) {
+  // FATAL: a non-empty line that will not parse means the transcript is being
+  // appended to (a half-written record) or is corrupt. Skipping it would let a
+  // stale prior grant survive past an event we cannot read, so refuse. A line
+  // that parses to a non-object (a bare null / string / number) is valid JSON but
+  // not a record — noise, not corruption — so it is skipped, not fatal, and never
+  // reaches the field reads below.
+  const recs = [];
+  for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
-    let obj;
+    let o;
     try {
-      obj = JSON.parse(line);
+      o = JSON.parse(line);
     } catch {
+      return false;
+    }
+    if (o === null || typeof o !== 'object') continue;
+    recs.push(o);
+  }
+
+  // The approval is a LEASE, not an existence fact: walk the transcript in line
+  // order and track whether the LATEST user decision is a grant. Each grant sets
+  // it true, each invalidate sets it false, neutral leaves it — so at the end
+  // `granted` is "the most recent user decision was to close, and nothing has
+  // expired it since", which is how a stale close and a queued change-of-mind
+  // read as NOT closed.
+  //
+  // Branch note: line order mixes an abandoned branch's records with the live
+  // ones. A leaf-pointer ancestry filter was tried and withdrawn — the transcript
+  // carries no authoritative leaf pointer (measured: 0 leafUuid / summary
+  // records), so a heuristic leaf can skip the real invalidator and PRESERVE a
+  // stale grant (a fail-open, not a conservative filter). Until such a pointer
+  // exists, a close on a branch abandoned under a neutral tail is a known
+  // 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
+    // PreCompact gate working (it sees the enqueue) and avoids double-counting the
+    // replay companion of an already-decided item (the /compact replay is not a
+    // fresh decision). popAll cancels the queue → invalidate. Delivery ops
+    // (dequeue, remove) carry no fresh decision here — a content-bearing remove of
+    // an NL queued command is handled by its queued_command attachment below.
+    if (o.type === 'queue-operation') {
+      if (o.operation === 'popAll') {
+        granted = false;
+        continue;
+      }
+      if (o.operation !== 'enqueue') continue;
+      const c = typeof o.content === 'string' ? o.content.trim() : '';
+      if (/^\/compact(?:\s|$)/.test(c))
+        granted = true; // a user compaction preserves the work → grant
+      else if (/^\/clear(?:\s|$)/.test(c))
+        granted = false; // abandons context → invalidate
+      else if (!c || c.startsWith('<task-notification>')) {
+        /* model-caused / empty — neutral */
+      } else if (isClosePattern(c)) {
+        /* NL close via the queue — the open dequeue gap: the producer cannot be
+           attributed (a peer/model enqueue wears the same shape), so no grant */
+      } else granted = false; // a queued non-close user intent → invalidate (change of mind)
       continue;
     }
-    // (2) /compact (queue-operation). Not /clear — see doc above.
-    if (
-      obj.type === 'queue-operation' &&
-      typeof obj.content === 'string' &&
-      /^\/compact(?:\s|$)/.test(obj.content.trim())
-    ) {
-      return true;
+
+    // remove-path delivery of a queued natural-language command (measured: the
+    // item leaves the queue as it is handed to the model, landing as an
+    // `attachment` of type queued_command with the prompt verbatim). A close here
+    // grants ONLY with an audited human producer — origin.kind "human", present
+    // on every 2.1.181+ user delivery (measured). A legacy origin-absent delivery
+    // cannot attest a producer, so it does not grant (fail-closed). A NON-close
+    // queued command (e.g. "keep working") is a fresh user intent and INVALIDATES
+    // a prior grant regardless of origin — that is what closes the re-close hole
+    // where a queued "continue" after a close leaves the stale lease live.
+    if (o.type === 'attachment' && o.attachment && o.attachment.type === 'queued_command') {
+      const prompt = typeof o.attachment.prompt === 'string' ? o.attachment.prompt : '';
+      const humanOrigin = !!(o.attachment.origin && o.attachment.origin.kind === 'human');
+      if (isClosePattern(prompt)) {
+        if (humanOrigin) granted = true;
+      } else if (prompt) {
+        granted = false;
+      }
+      continue;
     }
-    const content = (obj.message ?? obj).content;
-    if (!Array.isArray(content)) continue;
-    for (const b of content) {
-      if (!b || typeof b !== 'object') continue;
-      // record AskUserQuestion tool_use ids
-      if (b.type === 'tool_use' && b.name === 'AskUserQuestion' && b.id) {
-        askIds.add(b.id);
+
+    // Record AskUserQuestion tool_use ids (assistant record, always precedes its
+    // 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.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,
+    // 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;
       }
-      // (3) AskUserQuestion answer naming a close action — only when this
-      // tool_result actually answers a recorded AskUserQuestion. The answer lands
-      // in a role:user tool_result string: `… have been answered: "Q"="A". …`.
-      // Match the answer value(s) (the `="…"` side), never the question text, and
-      // run the SAME isClosePattern as the NL path so the two channels agree.
-      if (b.type === 'tool_result' && b.tool_use_id && askIds.has(b.tool_use_id)) {
+      granted = isClosePattern(userText);
+      continue;
+    }
+
+    // AskUserQuestion answer, correlated to a recorded AskUserQuestion, EXCLUDED
+    // and HARDENED. isModelReachableRecord keeps an injected / sdk / sidechain
+    // record from reaching the answer parser. is_error:false AND the host's
+    // success marker are required because a malformed AskUserQuestion echoes the
+    // raw input back in an is_error result, and the model authors the option
+    // labels. A close selection grants; any other real selection invalidates.
+    if (Array.isArray(content) && !isModelReachableRecord(o)) {
+      for (const b of content) {
+        if (!b || typeof b !== 'object') continue;
+        if (b.type !== 'tool_result' || !b.tool_use_id || !askIds.has(b.tool_use_id)) continue;
+        if (b.is_error === true) continue;
         const s = typeof b.content === 'string' ? b.content : JSON.stringify(b.content);
+        if (!/have been answered/.test(s)) continue;
+        let sawAnswer = false;
+        let sawClose = false;
         for (const m of s.matchAll(/="([^"]*)"/g)) {
-          if (isClosePattern(m[1])) return true;
+          sawAnswer = true;
+          if (isClosePattern(m[1])) sawClose = true;
         }
+        if (sawClose) granted = true;
+        else if (sawAnswer) granted = false;
       }
     }
   }
-  return false;
+  return granted;
+}
+
+/** The literal the user must type to approve a parked-overwrite batch. */
+export const APPROVAL_PHRASE = 'apply-proposals';
+
+/**
+ * True iff the transcript carries a user's TYPED approval of the batch this nonce
+ * was minted for — the authorization gate for a transcript-approved apply.
+ *
+ * Deliberately NOT hasUserCloseSignal. That function answers "did the user want to
+ * end the session", and it accepts a correlated AskUserQuestion answer as evidence
+ * (see above). Reusing it here would let a SESSION-CLOSE approval spend itself as an
+ * OVERWRITE approval: different authority, different question. Two gates, two
+ * matchers.
+ *
+ * Typed text only, and an AskUserQuestion click is refused ON PURPOSE. The model
+ * authors the option labels, and it authors them AFTER it has seen the nonce — so
+ * it could place `apply-proposals <nonce>` on a "no" option, on every option, or
+ * under a question that asks something else entirely. A click would prove a click.
+ * Typing the nonce proves the user produced THIS phrase.
+ *
+ * The nonce carries the freshness: it is minted (crypto-random) only once the diff
+ * has been re-read from disk and shown, so a turn that predates the diff cannot
+ * contain it, and `resolve` spends the challenge BEFORE it writes, so it cannot be
+ * replayed.
+ *
+ * extractUserMessageRecords does the de-pollution: it drops `isMeta` bodies
+ * (slash-command and skill text, so a doc that quotes this phrase cannot satisfy the
+ * gate), `promptSource: system|sdk`, Stop-hook feedback, and `tool_result` blocks (so
+ * neither a tool's output nor a Read of a file that contains the phrase counts).
+ * The model's own words are role:assistant and never reach it.
+ *
+ * Fail-closed: no path, a nonce that is not the minted shape, or an unreadable
+ * transcript all return false.
+ *
+ * @param {string} transcriptPath
+ * @param {string} nonce hex, as minted by `proposal challenge`
+ */
+export function hasTypedUserApproval(transcriptPath, nonce) {
+  if (!transcriptPath || typeof nonce !== 'string') return false;
+  // Pin the shape rather than accept any string: a caller that passed '' or a
+  // regex-ish value would otherwise turn the match into a wildcard.
+  if (!/^[a-f0-9]{32,}$/.test(nonce)) return false;
+  // A MESSAGE that IS the phrase, not a message that has the phrase somewhere in it.
+  // Line-exactness is not enough, because the user is TOLD to type this phrase and so
+  // it is natural to quote it back while hesitating:
+  //
+  //     I do not consent; I am only quoting the command:
+  //         apply-proposals <nonce>
+  //
+  // Every line-level matcher reads that as approval, and the user has authorized an
+  // overwrite by refusing one. The whole eligible message must be the phrase and
+  // nothing else, which is the bar the TTY channel has always held (`apply <id>`,
+  // alone, on the prompt). The two channels must not disagree about what consent
+  // looks like.
+  //
+  // Measured, not assumed: across 468 eligible user records in this project's
+  // transcripts, none carried a second text block and none carried injected
+  // system-reminder text, so a turn whose only content is the phrase survives
+  // extraction as exactly the phrase. A false negative costs a retype; a false
+  // positive costs the user's file.
+  const want = `${APPROVAL_PHRASE} ${nonce}`;
+  const records = extractUserMessageRecords(transcriptPath, Infinity);
+  return records.some((msg) => msg.trim() === want);
 }
 
 /**
@@ -2876,7 +4704,8 @@ export function isCloseReconfirmDeclined(transcriptPath) {
     // system/sdk synthetic prompts, and (via the array-content branch below)
     // tool_result blocks, which are role:'user' in the transcript but are NOT
     // user-typed text.
-    const isInjected = obj.isMeta === true || obj.promptSource === 'system' || obj.promptSource === 'sdk';
+    const isInjected =
+      obj.isMeta === true || obj.promptSource === 'system' || obj.promptSource === 'sdk';
     const role = msg.role ?? obj.role ?? obj.type;
     if (!isInjected && role === 'user') {
       if (typeof content === 'string') {
@@ -2962,7 +4791,15 @@ export function computeSessionGrowth(hypoDir) {
     // more expensive `git diff HEAD --unified=0` — Stop hook P95 win.
     // `-uall` expands untracked directories so a brand-new `pages/new.md`
     // isn't hidden behind a single `?? pages/` line.
-    const porcelain = spawnSync('git', ['-C', hypoDir, 'status', '--porcelain', '-uall'], {
+    // `-z`: NUL-separated, verbatim paths (see commitWikiChanges). The old
+    // newline/quote-strip parser left octal escapes in place, so Korean page
+    // names silently failed the `pages/`·`projects/` scope match and dropped
+    // out of the growth count.
+    // `-z`: NUL-separated, verbatim paths (see commitWikiChanges). The old
+    // newline/quote-strip parser left octal escapes in place, so Korean page
+    // names silently failed the `pages/`·`projects/` scope match and dropped
+    // out of the growth count.
+    const porcelain = spawnSync('git', ['-C', hypoDir, 'status', '--porcelain', '-uall', '-z'], {
       encoding: 'utf-8',
       timeout: 5000,
     });
@@ -2976,10 +4813,14 @@ export function computeSessionGrowth(hypoDir) {
     // intentionally excluded — they're scaffolding, not page growth.
     const inPagesScope = (file) =>
       file.endsWith('.md') && (file.startsWith('pages/') || file.startsWith('projects/'));
-    for (const line of (porcelain.stdout || '').split('\n')) {
-      if (!line) continue;
-      const xy = line.slice(0, 2);
-      const file = line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop().trim();
+    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); // destination path for a rename/copy
+      // A rename OR copy emits two records (`to\0from`); consume the trailing `from`.
+      if (xy[0] === 'R' || xy[1] === 'R' || xy[0] === 'C' || xy[1] === 'C') i++;
       if (!inPagesScope(file)) continue;
       if (xy === '??') {
         untrackedMd.push(file);
@@ -2987,7 +4828,8 @@ export function computeSessionGrowth(hypoDir) {
         continue;
       }
       hasTrackedMdChange = true;
-      if (xy.includes('A')) addedPages++;
+      // A copy's destination is a brand-new page, so it counts as added like `A`.
+      if (xy.includes('A') || xy.includes('C')) addedPages++;
       else if (xy.includes('M') || xy.includes('R')) updatedPages++;
     }
     if (!hasTrackedMdChange && untrackedMd.length === 0) return empty;
@@ -3079,3 +4921,65 @@ export function isIgnored(filePath, hypoDir, patterns) {
   }
   return false;
 }
+
+// ── visibility scope ─────────────────────────────────────────────────────────
+// The machine-scoped visibility namespace (`visibility_scope: machine:<device>`)
+// requires that the SAME device string is produced at write time (audit device
+// stamps) and at lookup time (the visibility filter) — otherwise a page never
+// matches its own machine. So this is the single source for both. NOT cached:
+// each call reads env fresh so in-process tests can override via HYPO_DEVICE
+// (os.hostname is not mockable). CR/LF are stripped so the value stays a single
+// frontmatter token.
+export function currentDevice() {
+  // Strip CR/LF BEFORE the fallback chain, not after: a HYPO_DEVICE of only
+  // CR/LF is truthy, so stripping after `||` would yield '' and make
+  // scopeVisible('machine:', '') pass — the empty-owner page must hide
+  // everywhere. Stripping first collapses such a value to '' so it falls through
+  // to hostname, keeping the result non-empty on every path.
+  const env = String(process.env.HYPO_DEVICE || '').replace(/[\r\n]/g, '');
+  if (env) return env;
+  const host = String(hostname() || '').replace(/[\r\n]/g, '');
+  return host || 'unknown';
+}
+
+// Extract the top-level `visibility_scope` from a page's raw content. Mirrors
+// scripts/lib/frontmatter.mjs normalization (top-level only, first-wins, strip a
+// whitespace-led trailing YAML comment, strip surrounding quotes) rather than
+// importing it: hooks deploy to ~/.claude/hooks/ with no external imports. The
+// five consumers must call this instead of a local last-wins/no-comment parser,
+// else a `machine:devA # note` value fails to match on its own machine. Returns
+// '' when absent (which scopeVisible treats as shared).
+export function readVisibilityScope(raw) {
+  const m = String(raw || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return '';
+  for (const line of m[1].split(/\r?\n/)) {
+    if (/^\s/.test(line) || /^-(\s|$)/.test(line)) continue; // nested / list item
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    if (line.slice(0, idx).trim() !== 'visibility_scope') continue;
+    return line
+      .slice(idx + 1)
+      .trim()
+      .replace(/\s+#.*$/, '')
+      .replace(/^["']|["']$/g, '');
+  }
+  return '';
+}
+
+// The single visibility decision, shared by lookup / query / file-watch /
+// page-usage / crystallize. `scopeValue` is a readVisibilityScope() output,
+// `device` a currentDevice() output. Prefix dispatch, fail-open on anything
+// unrecognized so the field is purely additive:
+//   ''/'shared'       → visible (the implicit default of every pre-existing page)
+//   'machine:<owner>' → visible only on the owning machine. Empty owner
+//                       (`machine:`) hides everywhere: '' can never equal
+//                       currentDevice()'s non-empty fallback.
+//   'agent:<id>'      → visible; value space reserved, no writer yet (forward-compat)
+//   anything else     → visible (fail-open)
+export function scopeVisible(scopeValue, device) {
+  const v = String(scopeValue || '').trim();
+  if (v === '' || v === 'shared') return true;
+  if (v.startsWith('machine:')) return v.slice('machine:'.length) === device;
+  if (v.startsWith('agent:')) return true;
+  return true;
+}