hypomnema 1.6.2 → 1.7.1

package/hooks/hypo-auto-commit.mjs

@@ -2,32 +2,109 @@
 /**
  * hypo-auto-commit.mjs — Stop hook
  *
- * At session end: stage all changes, commit if any, then pull+push to sync remote.
+ * At session end: stage this session's touched paths, commit if any, then
+ * pull+push to sync remote.
+ *
+ * Scoped, not whole-tree: this no longer sweeps the entire working tree. The
+ * scope is this session's accumulated touched-paths set (hypo-auto-stage.mjs
+ * writes, plus whatever the earlier Stop-chain generators, hot-rebuild and
+ * session-record, appended for the same session_id). No session_id means
+ * nothing was ever accumulated, so the scoped commit is skipped cleanly;
+ * never a whole-tree fallback.
+ *
+ * PEEK, don't drain, and hold ONE lock across peek+commit+clear
+ * (commitTouchedPaths, hypo-shared.mjs): a drain-then-requeue-on-failure
+ * design was tried and dropped — the requeue write is itself a fallible
+ * operation (lock-timeout, I/O), so a commit failure could still lose the
+ * scope in the narrow window between the drain and the requeue. A peek
+ * that released its lock before the commit, then a SEPARATE clear
+ * afterward, was also tried and dropped — a `recordTouchedPaths` for a
+ * path already in the just-peeked set could land in the window between the
+ * commit and the clear and be silently wiped out by it (the set only
+ * tracks path presence, not a version, so that write is indistinguishable
+ * from the one already peeked). commitTouchedPaths holds ONE per-session
+ * lock across the whole peek → commit → clear window, so neither loss mode
+ * is possible: nothing is deleted until the commit has actually succeeded,
+ * and no accumulate can land inside the window at all.
  */
 
 import { spawnSync } from 'child_process';
-import { HYPO_DIR, syncRemote, commitWikiChanges } from './hypo-shared.mjs';
+import {
+  HYPO_DIR,
+  syncRemote,
+  commitWikiChanges,
+  commitTouchedPaths,
+  vaultCommitLockTarget,
+  withFileLock,
+} from './hypo-shared.mjs';
 
 function hasRemote() {
   const r = spawnSync('git', ['-C', HYPO_DIR, 'remote'], { encoding: 'utf-8', timeout: 30000 });
   return (r.stdout || '').trim().length > 0;
 }
 
-// Stage + commit via the shared helper (same .hypoignore filter the apply path
-// uses). A real commit failure short-circuits before sync, exactly as
-// the inline logic did; "nothing to commit" is success and falls through to sync.
-const result = commitWikiChanges(HYPO_DIR);
-if (!result.committed) {
-  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
-  process.exit(0);
+// Overridable so a test can force a fast lock-timeout instead of waiting out
+// the real default (mirrors crystallize.mjs's HYPO_APPEND_LOCK_TIMEOUT_MS).
+const VAULT_LOCK_TIMEOUT_MS = Number(process.env.HYPO_VAULT_LOCK_TIMEOUT_MS) || 5000;
+
+let input = {};
+try {
+  const raw = await new Promise((r) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => r(d));
+  });
+  input = JSON.parse(raw || '{}') || {};
+} catch {
+  input = {};
 }
+const sessionId = input.session_id || input.sessionId || null;
+
+// Stage + commit + sync as one critical section, serialized against every
+// other writer of this vault (the crystallize.mjs --apply-session-close path
+// holds the SAME lock around its own stage+commit). Without this, two
+// concurrent sessions on a shared vault could interleave `git add`/`git
+// commit`/`git pull`/`git push`. This does NOT gate pushes on whole-tree
+// cleanliness: a scoped commit may legitimately leave other sessions' dirty
+// files behind, and a `git pull --no-rebase` failure from that residual is
+// already logged via appendSyncFailure and surfaced by doctor/session-start.
+// Full cross-session isolation is out of scope (it needs separate worktrees).
+//
+// The vault lock (shared with crystallize.mjs's apply commit) serializes
+// git operations across concurrent sessions on this vault; the per-session
+// touched-paths lock commitTouchedPaths takes internally is a DIFFERENT
+// lock file, so the two nest without any ordering conflict (vault lock is
+// always acquired first here; accumulation elsewhere only ever takes the
+// per-session lock, never the vault lock).
+try {
+  withFileLock(
+    vaultCommitLockTarget(HYPO_DIR),
+    () => {
+      // Peek this session's scope, run the scoped commit, and — only on
+      // success — clear exactly what committed, ALL under one hold of the
+      // per-session lock. See commitTouchedPaths's docstring for why a
+      // commit failure or a same-path race can't lose anything under this.
+      const result = commitTouchedPaths(HYPO_DIR, sessionId, (paths) =>
+        commitWikiChanges(HYPO_DIR, paths),
+      );
+      if (!result.committed) return;
 
-if (hasRemote()) {
-  // pull/push failures must not stop the session, but they can no longer be
-  // swallowed silently — syncRemote records each to .cache/sync-state.json and,
-  // on a merge conflict, aborts the merge so the tree is never left half-merged
-  // (part of the v1.4 sync hardening). session-start + doctor surface the result next session.
-  syncRemote(HYPO_DIR);
+      if (hasRemote()) {
+        // pull/push failures must not stop the session, but they can no longer be
+        // swallowed silently — syncRemote records each to .cache/sync-state.json and,
+        // on a merge conflict, aborts the merge so the tree is never left half-merged
+        // (part of the v1.4 sync hardening). session-start + doctor surface the result next session.
+        syncRemote(HYPO_DIR);
+      }
+    },
+    { timeoutMs: VAULT_LOCK_TIMEOUT_MS },
+  );
+} catch {
+  // Lock-timeout (or an unexpected lock error) on the OUTER vault lock: we
+  // never entered the critical section, so commitTouchedPaths never ran —
+  // the touched-paths file is untouched on disk, and the next Stop retries
+  // this session's commit from the same scope. Best-effort, like every
+  // other step in this hook.
 }
 
 console.log(JSON.stringify({ continue: true, suppressOutput: true }));

package/hooks/hypo-auto-minimal-crystallize.mjs

@@ -123,10 +123,20 @@ function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
   // an install/transcript path contains spaces (display text only — never exec'd
   // here).
   const transcriptHint = transcriptPath ? ` --transcript-path="${transcriptPath}"` : '';
+  // Recovery command carries EVIDENCE, never the recency-derived close.project.
+  // The evidence-backed attribution is a singleton close scope (transcript
+  // close-files ∪ this marker's projects); when it is unambiguous, embed it as
+  // --project so the re-run is one-shot instead of failing closed for lack of
+  // evidence. The session cwd (from the payload) rides along so the re-run's own
+  // session-cwd close check runs against the same project this Stop evaluated.
+  const scope = gate?.close?.scope || [];
+  const evidenceProject = scope.length === 1 ? scope[0] : null;
+  const projectHint = evidenceProject ? ` --project=${evidenceProject}` : '';
+  const cwdHint = opts.sessionCwd ? ` --session-cwd="${opts.sessionCwd}"` : '';
   const cliBase = PKG_ROOT ? `node "${join(PKG_ROOT, 'scripts', 'crystallize.mjs')}"` : null;
   const markCmd = cliBase
-    ? `${cliBase} --mark-session-closed --session-id=${sessionId}${transcriptHint}`
-    : `/hypo:crystallize (session_id=${sessionId}${transcriptHint})`;
+    ? `${cliBase} --mark-session-closed --session-id=${sessionId}${projectHint}${transcriptHint}${cwdHint}`
+    : `/hypo:crystallize (session_id=${sessionId}${projectHint}${transcriptHint})`;
   // The log-only escape hatch for a non-project (wiki/tooling-only)
   // session. Offered ONLY as an explicit alternative when a close blocker is
   // present — never as the default recovery, so a real project session is not
@@ -150,7 +160,9 @@ function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
     // Only when a project-close blocker is what's holding the session: a
     // non-project session has nothing to close, so offer log-only as the way out
     // (Claude decides whether this session is project-scoped — no auto-attribution).
-    if (gate.blockers.some((b) => b.type === 'close')) {
+    // A session-cwd close blocker (the session's own cwd project is unstarted) is
+    // the same kind of project-close hold, so it gets the same escape.
+    if (gate.blockers.some((b) => b.type === 'close' || b.type === 'close-cwd')) {
       reason += ` If this was a non-project (wiki/tooling-only) session with no project to close, run \`${logOnlyCmd}\` instead (log-only close, no project attribution).`;
     }
   } else {
@@ -202,6 +214,9 @@ process.stdin.on('end', () => {
 
     const sessionId = payload.session_id || payload.sessionId || null;
     const transcriptPath = payload.transcript_path || payload.transcriptPath || null;
+    // Authoritative session cwd (the one verified cwd source) for the session-cwd
+    // close check below. Absent on older Claude Code payloads → the check is skipped.
+    const sessionCwd = payload.cwd || null;
 
     // 3. substantial-session gate. Pure Q&A / incidental-lookup sessions skip
     // the block; mutating sessions AND high-volume read-only investigations
@@ -220,10 +235,49 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // 5. close already verified for this session_id.
-    if (sessionId && readSessionClosedMarker(HYPO_DIR, sessionId)) {
-      emitContinue();
-      return;
+    // Read-only /compact gate (same precompactGateStatus the real PreCompact hook
+    // uses) sharpens the block message and, with sessionCwd, backs the session-cwd
+    // close check below. The hook NEVER writes the marker here (file-header
+    // invariant); this is read-only. Any error → null → emitBlock falls back to the
+    // generic message (fail-open). Computed lazily: the common closed-session path
+    // (a project marker whose cwd project is complete) still short-circuits without
+    // paying the gate cost, unless a cwd signal makes the cwd check meaningful.
+    let gate = null;
+    const computeGate = () => {
+      try {
+        return precompactGateStatus(HYPO_DIR, {
+          ...(transcriptPath ? { transcriptPath } : {}),
+          ...(sessionCwd ? { sessionCwd } : {}),
+          ...(sessionId ? { sessionId } : {}),
+        });
+      } catch {
+        return null;
+      }
+    };
+
+    // 5. close already verified for this session_id — but a project marker only
+    // attests the project(s) it recorded. If THIS session's cwd project still has
+    // an unstarted close, honoring the marker would end the session green while
+    // that project stays open (the session-cwd false-green). So re-check the cwd
+    // project before accepting a project marker. A log-only marker (non-project
+    // session) is exempt, and without a cwd signal we accept the marker as before
+    // (back-compat with payloads that carry no cwd).
+    if (sessionId) {
+      const marker = readSessionClosedMarker(HYPO_DIR, sessionId);
+      if (marker) {
+        if (marker.scope === 'log-only' || !sessionCwd) {
+          emitContinue();
+          return;
+        }
+        gate = computeGate();
+        const cwdBlocked = !!gate?.blockers?.some((b) => b.type === 'close-cwd');
+        if (!cwdBlocked) {
+          emitContinue();
+          return;
+        }
+        // marker present but the session's cwd project close is incomplete: fall
+        // through to block, reusing the gate computed above.
+      }
     }
 
     // 6. block — but only when we have a session_id to address the recovery
@@ -234,18 +288,7 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // Read-only /compact gate (same precompactGateStatus the real
-    // PreCompact hook uses) sharpens the block message — distinguishes "close
-    // is compact-ready, only the marker is missing" from "there are real
-    // blockers". The hook NEVER writes the marker here (file-header invariant);
-    // this is read-only. Any error → null → emitBlock falls back to the generic
-    // message (fail-open).
-    let gate = null;
-    try {
-      gate = precompactGateStatus(HYPO_DIR, transcriptPath ? { transcriptPath } : {});
-    } catch {
-      gate = null;
-    }
+    if (!gate) gate = computeGate();
 
     // Reconfirm decision (conditional-close-reconfirm): "close" and
     // "work-incomplete" together are exactly the case where the transcript's
@@ -269,7 +312,7 @@ process.stdin.on('end', () => {
       return;
     }
 
-    emitBlock(sessionId, transcriptPath, gate, { reconfirm: workIncomplete });
+    emitBlock(sessionId, transcriptPath, gate, { reconfirm: workIncomplete, sessionCwd });
   } catch (err) {
     // Fail-open on any unexpected error.
     process.stderr.write(`[hypo-auto-minimal-crystallize] error: ${err?.message ?? String(err)}\n`);

package/hooks/hypo-auto-stage.mjs

@@ -6,7 +6,17 @@
  */
 
 import { spawnSync } from 'child_process';
-import { HYPO_DIR, loadHypoIgnore, isIgnored } from './hypo-shared.mjs';
+import { relative } from 'path';
+import { HYPO_DIR, loadHypoIgnore, isIgnored, recordTouchedPaths } from './hypo-shared.mjs';
+import { advanceBaseForWrite, hashContent } from './base-store.mjs';
+
+// Tools that REPLACE file bytes. The base advance below must fire only for these:
+// this hook has no matcher in hooks.json (it runs on every PostToolUse), and a
+// read-only tool like Read also carries `tool_input.file_path`. Without this
+// allowlist, merely Reading a target another session had drifted would advance
+// the base to that other session's bytes — silently defeating the write=proposal
+// guard at close. tool_name, not file_path, is the write signal.
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
 
 let input = {};
 try {
@@ -29,6 +39,36 @@ if (filePath.startsWith(HYPO_DIR + '/') || filePath === HYPO_DIR) {
   if (patterns.length === 0 || !isIgnored(filePath, HYPO_DIR, patterns)) {
     spawnSync('git', ['-C', HYPO_DIR, 'add', filePath], { stdio: 'ignore' });
   }
+
+  if (WRITE_TOOLS.has(input.tool_name)) {
+    const rel = relative(HYPO_DIR, filePath);
+
+    // Accumulate this write into the session's scoped auto-commit
+    // set, keyed by session_id (no-op without one; never a shared bucket).
+    // hypo-auto-commit.mjs drains this at Stop instead of sweeping the whole
+    // working tree, so another session's concurrent writes to this vault
+    // never land in THIS session's commit.
+    recordTouchedPaths(HYPO_DIR, input.session_id, rel);
+
+    // Write=proposal gate provenance: when this session's own write lands on one of
+    // the overwrite targets it snapshotted at start, advance that target's base so
+    // the close guard reads the change as "I wrote this", not "someone else did"
+    // (which would fail safe into a false proposal against the session's own edit).
+    // Self-scoping — a no-op unless the path is a tracked base key — so it runs
+    // regardless of .hypoignore (provenance is independent of privacy). Best-effort.
+    //
+    // The Write tool carries its full `content`, so advance to the bytes THIS
+    // session wrote (race-safe: a concurrent write landing between the tool and
+    // this hook cannot be adopted as our base). Edit/MultiEdit have no full content
+    // in the payload, so they fall back to a post-write disk read.
+    if (input.session_id) {
+      const known =
+        input.tool_name === 'Write' && typeof input.tool_input?.content === 'string'
+          ? hashContent(input.tool_input.content)
+          : null;
+      advanceBaseForWrite(HYPO_DIR, input.session_id, rel, filePath, known);
+    }
+  }
 }
 
 console.log(JSON.stringify({ continue: true, suppressOutput: true }));

package/hooks/hypo-close-guard.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * hypo-close-guard.mjs — PreToolUse hook
+ *
+ * SCOPE: this guard closes the direct Write/Edit/MultiEdit bypass only — it is
+ * not a general unauthorized-close catcher. A write executed via Bash (shell
+ * redirection, sed, a script) never reaches PreToolUse's tool_input inspection
+ * and is out of scope. The regular `/hypo:crystallize --apply-session-close`
+ * path runs via Bash and already validates the transcript's close signal
+ * before it writes, so it neither trips this guard nor needs to.
+ *
+ * Intercepts a Write/Edit/MultiEdit BEFORE it lands, when it targets one of the
+ * two close-artifact files (session-state.md, hot.md). doctor's
+ * detectSessionCloseArtifact (hypo-shared.mjs, post-hoc) only ever sees a file
+ * AFTER the write, and only fires on 마감/종료 vocabulary — a wordless full
+ * rewrite (the 2026-07-28 hot.md incident) reads clean to it, because there is
+ * no prior version to diff against.
+ *
+ * Here there is no such blind spot: the PRIMARY signal is structural, not
+ * lexical. recordTouchedPaths (populated by hypo-auto-stage's PostToolUse,
+ * which has already run for every earlier write this session) already tracks
+ * which close-artifact file(s) this session wrote. If the write in front of us
+ * targets one of a project's pair (projects/<slug>/session-state.md,
+ * projects/<slug>/hot.md) and the OTHER one is already in that set, this
+ * session is rewriting both — regardless of what either file's text says. The
+ * pair is scoped to the SAME project directory on purpose: pairing by basename
+ * alone would fire on the root hot.md (which every session's Stop-chain
+ * hypo-hot-rebuild.mjs legitimately rewrites) against an unrelated project's
+ * session-state.md — a false positive, not a close. Root hot.md is therefore
+ * never a structural pair member; it can still trip the lexical signal below
+ * if it is literally rewritten with 마감/종료 wording.
+ *
+ * KNOWN WINDOW: the structural signal is only alive for one turn. Stop's
+ * auto-commit chain (hypo-auto-commit.mjs → commitTouchedPaths) commits and
+ * then CLEARS a session's touched-paths set every time Stop runs. Write
+ * session-state.md in turn 1 and hot.md in turn 2 (Stop runs in between) and
+ * the touched-paths file no longer has the first path — structuralHit reads
+ * false. This is accepted, not fixed: a real close writes both files in the
+ * same turn (see the JSDoc coverage note in hypo-shared.mjs's
+ * detectSessionCloseArtifact), so the main path is still caught; a fresh
+ * cross-turn persistence store is out of this guard's scope. Once the window
+ * closes, only the lexical signal (detectSessionCloseArtifact on the write's
+ * own new text) can still catch a close. See the test that pins this window
+ * (using the real commitTouchedPaths path, not a bare drain) in
+ * tests/close-hooks-gate.test.mjs.
+ *
+ * CASE FOLDING: the basename gate and the structural pairing comparison below
+ * are lowercase-folded. macOS's default volume is case-insensitive, so a write
+ * to `projects/foo/HOT.md` targets the same file `hot.md` does, and comparing
+ * basenames verbatim would read it as "not a close-artifact file" and skip the
+ * structural check entirely. This folding covers only OUR OWN comparisons;
+ * detectSessionCloseArtifact (hypo-shared.mjs, untouched here) does its own
+ * case-sensitive basename check internally, so a case-varied write can still
+ * dodge the LEXICAL signal — but the structural signal does not depend on file
+ * content at all, so it still catches it.
+ *
+ * detectSessionCloseArtifact runs as a SECONDARY trigger regardless of the
+ * structural outcome, so a lone wordy close is caught before its pair even
+ * lands, and the two defenses share one definition of "close" instead of
+ * drifting apart.
+ *
+ * UNDECIDABLE vs BROKEN: the structural signal reads the session's
+ * touched-paths cache directly (readTouchedPathsOrUndecidable below), not via
+ * hypo-shared's peekTouchedPaths, because peekTouchedPaths collapses a lock
+ * timeout, a corrupt cache file, AND a genuinely-empty session into the exact
+ * same `[]` — indistinguishable from the caller's side. Folding all three into
+ * "no structural signal, allow" would let a wordless close slip through
+ * exactly when this guard's own bookkeeping is unreliable, which is the worst
+ * moment for it to go quiet. So an undecidable read (lock timeout / corrupt
+ * cache / no session_id) is instead treated as a HIT — it folds into the same
+ * `ask` branch as a genuine structural match. This is deliberately distinct
+ * from the hook ITSELF breaking (unparseable stdin, an unexpected exception):
+ * that still exits silently below, because a broken guard must never block
+ * the user's actual work. readTouchedPathsOrUndecidable is built from the same
+ * exported primitives peekTouchedPaths itself uses (withFileLock,
+ * touchedPathsPath) — no new read-only API was added to hypo-shared.mjs for
+ * this.
+ *
+ * NO EXPLICIT ALLOW: `permissionDecision: "allow"` is not "stay quiet" — it
+ * tells Claude Code to bypass the user's NORMAL permission prompt for this
+ * tool call outright. This hook has no matcher (see NO MATCHER below), so it
+ * runs in front of every tool call, Bash included; printing an explicit allow
+ * anywhere would auto-approve permission prompts this guard has no business
+ * touching, which is the opposite of what a "confirm before a close" guard is
+ * for. So every pass-through path below prints NOTHING and exits 0, leaving
+ * Claude Code's normal permission policy exactly as it was. Only a genuine
+ * `ask` hit ever writes to stdout.
+ *
+ * A hit is never a deny. The hook only ASKS
+ * (hookSpecificOutput.permissionDecision = "ask") — the harness turns that into
+ * a confirmation in front of the write; approval stays with the human.
+ *
+ * NO MATCHER: this hook is registered under PreToolUse with no matcher (this
+ * repo's installer does not carry matchers through to settings — see
+ * scripts/init.mjs's `_extractFileNames` — and no other hook here uses one
+ * either), so it runs on every tool call. The early-return order below exists
+ * for exactly that: a non-write tool, or a write outside HYPO_DIR, returns
+ * before anything else runs.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { relative } from 'path';
+import {
+  HYPO_DIR,
+  detectSessionCloseArtifact,
+  hasUserCloseSignal,
+  isGateSkipped,
+  touchedPathsPath,
+  withFileLock,
+} from './hypo-shared.mjs';
+
+const CLOSE_ARTIFACT_BASENAMES = new Set(['session-state.md', 'hot.md']);
+// Mirrors hypo-auto-stage.mjs's WRITE_TOOLS: the tools that replace file bytes.
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
+
+// The write's own new text. Write carries the whole file; Edit/MultiEdit carry
+// only the replaced snippet(s) — good enough for detectSessionCloseArtifact,
+// which matches a single bold heading line, not the whole document.
+function newTextOf(toolName, toolInput) {
+  if (toolName === 'Write') {
+    return typeof toolInput?.content === 'string' ? toolInput.content : '';
+  }
+  if (toolName === 'Edit') {
+    return typeof toolInput?.new_string === 'string' ? toolInput.new_string : '';
+  }
+  if (toolName === 'MultiEdit' && Array.isArray(toolInput?.edits)) {
+    return toolInput.edits
+      .map((e) => (typeof e?.new_string === 'string' ? e.new_string : ''))
+      .join('\n');
+  }
+  return '';
+}
+
+// See "UNDECIDABLE vs BROKEN" above. `{ok: true, paths}` on a clean read
+// (including a genuinely absent file — never touched this session, not an
+// error); `{ok: false}` when the read cannot be trusted (no session_id, a
+// corrupt/non-array cache file, or a lock timeout).
+function readTouchedPathsOrUndecidable(hypoDir, sessionId) {
+  if (!sessionId) return { ok: false };
+  const path = touchedPathsPath(hypoDir, sessionId);
+  try {
+    return withFileLock(path, () => {
+      if (!existsSync(path)) return { ok: true, paths: [] };
+      try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!Array.isArray(parsed)) return { ok: false }; // corrupt shape
+        return { ok: true, paths: parsed.filter((p) => typeof p === 'string' && p) };
+      } catch {
+        return { ok: false }; // corrupt/unreadable JSON
+      }
+    });
+  } catch {
+    return { ok: false }; // lock timeout
+  }
+}
+
+let input = {};
+try {
+  const raw = await new Promise((r) => {
+    let d = '';
+    process.stdin.on('data', (c) => (d += c));
+    process.stdin.on('end', () => r(d));
+  });
+  input = JSON.parse(raw);
+} catch (err) {
+  // The hook ITSELF failed to read its own input — stay silent (see NO
+  // EXPLICIT ALLOW above); never write a permission decision over garbage.
+  process.stderr.write(`[hypo-close-guard] error: ${err?.message ?? String(err)}\n`);
+  process.exit(0);
+}
+
+try {
+  if (isGateSkipped() || !WRITE_TOOLS.has(input.tool_name)) {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path ?? '';
+  if (!filePath || !(filePath === HYPO_DIR || filePath.startsWith(HYPO_DIR + '/'))) {
+    process.exit(0);
+  }
+
+  const rel = relative(HYPO_DIR, filePath);
+  const relParts = rel.split(/[\\/]/);
+  const base = relParts[relParts.length - 1];
+  const baseLower = base.toLowerCase();
+  if (!CLOSE_ARTIFACT_BASENAMES.has(baseLower)) {
+    process.exit(0);
+  }
+
+  // Structural signal (primary): the OTHER close-artifact file of the SAME
+  // project already written this session — projects/<slug>/session-state.md
+  // paired with projects/<slug>/hot.md ONLY (case-folded). A root hot.md
+  // (relParts.length !== 3, or not under "projects/") is never a pair member.
+  const otherBaseLower = baseLower === 'hot.md' ? 'session-state.md' : 'hot.md';
+  let structuralHit = false;
+  let structuralUndecidable = false;
+  if (relParts.length === 3 && relParts[0].toLowerCase() === 'projects') {
+    const otherPathLower = `${relParts[0].toLowerCase()}/${relParts[1].toLowerCase()}/${otherBaseLower}`;
+    const touchedResult = readTouchedPathsOrUndecidable(HYPO_DIR, input.session_id);
+    if (!touchedResult.ok) {
+      structuralUndecidable = true; // see "UNDECIDABLE vs BROKEN" above
+    } else {
+      structuralHit = touchedResult.paths.some((p) => p.toLowerCase() === otherPathLower);
+    }
+  }
+
+  // Lexical signal (secondary): same predicate doctor uses post-hoc, run here
+  // on the write's own new text.
+  const lexicalHit = detectSessionCloseArtifact({
+    path: filePath,
+    content: newTextOf(input.tool_name, input.tool_input),
+  }).matched;
+
+  if (!structuralHit && !structuralUndecidable && !lexicalHit) {
+    process.exit(0);
+  }
+
+  if (hasUserCloseSignal(input.transcript_path ?? null)) {
+    process.exit(0);
+  }
+
+  const why = structuralUndecidable
+    ? `whether session-state.md and hot.md are both being rewritten this session could not be determined (touched-paths cache unreadable or no session_id)`
+    : structuralHit
+      ? `both session-state.md and hot.md are being rewritten this session`
+      : `this write reads as a close announcement (마감/종료 wording)`;
+
+  console.log(
+    JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason:
+          `[WIKI CLOSE GUARD] ${rel} — ${why}, but no user close signal was seen ` +
+          `in this session. Confirm with the user before writing: did they actually ` +
+          `ask to close the session?\n` +
+          `To bypass: set HYPO_SKIP_GATE=1`,
+      },
+    }),
+  );
+} catch (err) {
+  // The hook ITSELF broke (unexpected exception) — stay silent, same as the
+  // stdin-parse failure above: a broken guard must never block real work.
+  process.stderr.write(`[hypo-close-guard] error: ${err?.message ?? String(err)}\n`);
+}

package/hooks/hypo-cwd-change.mjs

@@ -24,6 +24,9 @@ import {
   pickProjectByCwd,
   collectProjectWorkingDirs,
   buildVaultOrientation,
+  currentDevice,
+  scopeVisible,
+  readVisibilityScope,
 } from './hypo-shared.mjs';
 
 const PROJECTS_DIR = join(HYPO_DIR, 'projects');
@@ -32,10 +35,32 @@ const MAX_CHARS = 3000;
 
 // Privacy guard: a .hypoignore-matched hot.md must not be
 // re-emitted into additionalContext on cwd change.
+//
+// Visibility guard: same contract as hypo-file-watch and hypo-session-start. A
+// machine-scoped hot.md stays off every machine but its owner. Scope is read
+// from the RAW content before the MAX_CHARS slice, since slicing first could cut
+// the frontmatter off and fail open. The root hot.md carries no frontmatter, so
+// it reads as '' and passes as shared.
 function readIfNotIgnored(path, patterns) {
   if (!path) return null;
   if (patterns.length > 0 && isIgnored(path, HYPO_DIR, patterns)) return null;
-  return readFileSync(path, 'utf-8').slice(0, MAX_CHARS);
+  const raw = readFileSync(path, 'utf-8');
+  if (!scopeVisible(readVisibilityScope(raw), currentDevice())) return null;
+  return raw.slice(0, MAX_CHARS);
+}
+
+// Scoped-out is not absent. Both make readIfNotIgnored return null, but the
+// absent-case placeholder tells the model the file "will be created at session
+// close". On a foreign machine that invites it to author over a hot.md that
+// exists and belongs elsewhere. Report the fact, never the withheld body.
+function isScopedOut(path, patterns) {
+  try {
+    if (!path || !existsSync(path)) return false;
+    if (patterns.length > 0 && isIgnored(path, HYPO_DIR, patterns)) return false;
+    return !scopeVisible(readVisibilityScope(readFileSync(path, 'utf-8')), currentDevice());
+  } catch {
+    return false;
+  }
 }
 
 function findProjectHot(cwd) {
@@ -87,7 +112,11 @@ process.stdin.on('end', () => {
 
     if (newHit) {
       const fromFile = readIfNotIgnored(newHit.hotPath, ignorePatterns);
-      const content = fromFile ?? '(no hot.md yet — will be created at session close)';
+      const content =
+        fromFile ??
+        (isScopedOut(newHit.hotPath, ignorePatterns)
+          ? '(hot.md for this project is scoped to another machine and is not visible here)'
+          : '(no hot.md yet — will be created at session close)');
       // arm the first-prompt marker so the NEXT user prompt re-triggers
       // hypo-first-prompt, which forces a "Resuming <project>" summary line.
       // Only arm when real hot content was actually injected — if hot.md is

package/hooks/hypo-file-watch.mjs

@@ -8,7 +8,14 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
-import { HYPO_DIR, loadHypoIgnore, isIgnored } from './hypo-shared.mjs';
+import {
+  HYPO_DIR,
+  loadHypoIgnore,
+  isIgnored,
+  currentDevice,
+  scopeVisible,
+  readVisibilityScope,
+} from './hypo-shared.mjs';
 
 const MAX_CHARS = 2000;
 
@@ -43,7 +50,19 @@ process.stdin.on('end', () => {
       return;
     }
 
-    const content = readFileSync(filePath, 'utf-8').slice(0, MAX_CHARS);
+    const fileRaw = readFileSync(filePath, 'utf-8');
+
+    // Visibility guard: a machine-scoped page (visibility_scope: machine:<owner>)
+    // must not be re-injected on a machine other than its owner. Read the scope
+    // from the raw, unsliced content — slicing to MAX_CHARS first could cut the
+    // frontmatter off and silently make every scoped page pass fail-open.
+    const scope = readVisibilityScope(fileRaw);
+    if (!scopeVisible(scope, currentDevice())) {
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+      return;
+    }
+
+    const content = fileRaw.slice(0, MAX_CHARS);
     const relPath = filePath.replace(HYPO_DIR + '/', '');
 
     console.log(