hypomnema 1.8.2 → 1.9.0

package/hooks/hypo-auto-commit.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * hypo-auto-commit.mjs — Stop hook
+ * hypo-auto-commit.mjs: Stop chain stage 3 (spawned by hypo-stop.mjs)
  *
  * At session end: stage this session's touched paths, commit if any, then
  * pull+push to sync remote.
@@ -31,11 +31,15 @@
 import { spawnSync } from 'child_process';
 import {
   HYPO_DIR,
-  syncRemote,
+  pullRemote,
+  pushRemote,
+  resolvePushTarget,
   commitWikiChanges,
   commitTouchedPaths,
   vaultCommitLockTarget,
   withFileLock,
+  rootHotProjectionIsCurrent,
+  writeRootHotHealthNotice,
 } from './hypo-shared.mjs';
 
 function hasRemote() {
@@ -76,6 +80,27 @@ const sessionId = input.session_id || input.sessionId || null;
 // 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).
+//
+// The PUSH is deliberately not in here (review r5-w4 major 2). `git pull
+// --no-rebase` rewrites working-tree files, so it stays under the lock with
+// the commit. `git push` changes nothing locally, and it is a network round
+// trip with a 30s spawn timeout: holding the vault lock across it let one
+// session's Stop own the vault for up to a minute, while a sibling
+// SessionStart needs that same lock TWICE (its own `git pull` and the root
+// hot.md projection write) at 5s each, out of a 30s hook budget. The pushable
+// decision is made inside the lock and acted on after it is released.
+//
+// "The push changes nothing locally" was the whole justification for that
+// split, and it was only half true (codex major). What the push sends is
+// decided at push time from HEAD, so a sibling session that commits in the
+// window between the unlock and the push moves HEAD, and a bare `git push`
+// sends THEIR commit instead of the one this hook just made and verified.
+// So the target is pinned inside the lock, not just the decision to push:
+// `pushTarget` names one commit object and one fully-qualified remote ref, and
+// pushRemote sends exactly that or declines. See pushRemote's own comment for
+// the half this does NOT close: a client-side pre-push hook still runs
+// arbitrary code, from outside the lock, on this working tree.
+let pushTarget = null;
 try {
   withFileLock(
     vaultCommitLockTarget(HYPO_DIR),
@@ -84,17 +109,55 @@ try {
       // 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),
-      );
+      const result = commitTouchedPaths(HYPO_DIR, sessionId, (paths) => {
+        // BLOCKER fix (r5-w1.md): 'hot.md' being IN this session's
+        // touched-paths set only ever proves this session once intended to
+        // write it, never that the bytes on disk right now are what it
+        // actually wrote: a scan error at SessionStart, a lock-timeout on
+        // the post-write record, or a claim simply outliving a later
+        // mid-session edit can all leave the claim standing over content
+        // this session never produced. Re-verify at this last possible
+        // moment, right before staging, instead of trying to revoke the
+        // claim on every branch that can go wrong upstream: a mismatch means
+        // whatever is on disk did not come from this session's own write, so
+        // it is dropped from THIS commit rather than swept in. It is not
+        // lost: the next SessionStart/Stop that manages a successful scan
+        // backs it up through the same ownership check before overwriting.
+        // n1 fix: sessionId, not just HYPO_DIR, since a sibling session's write
+        // updates the global ownership hash too, so this session's own
+        // receipt must independently confirm it produced the current bytes.
+        const scoped = rootHotProjectionIsCurrent(HYPO_DIR, sessionId)
+          ? paths
+          : paths.filter((p) => p !== 'hot.md');
+        if (scoped.length !== paths.length) {
+          writeRootHotHealthNotice(
+            HYPO_DIR,
+            '루트 hot.md이 이번 세션이 실제로 쓴 내용과 달라 이번 커밋에서 제외했습니다. 다음 세션 시작/종료 시 다시 확인됩니다.',
+          );
+        }
+        return commitWikiChanges(HYPO_DIR, scoped);
+      });
       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);
+        // swallowed silently: pullRemote/pushRemote record each to
+        // .cache/sync-state.json and, on a merge conflict, the pull 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.
+        //
+        // A conflicting pull leaves this branch diverged, so the push is
+        // suppressed rather than deferred: the same ordering guarantee
+        // syncRemote has always had, now carried across the lock boundary by
+        // this target instead of by a `return`.
+        //
+        // Resolved AFTER the pull, not from `result.sha`: a clean
+        // `git pull --no-rebase` can land a merge commit on top of ours, and
+        // pushing the pre-merge sha would be rejected as a non-fast-forward.
+        // HEAD here is still under the lock, so it is this session's commit
+        // (plus whatever the pull brought down) and nothing a sibling added
+        // after the unlock.
+        if (!pullRemote(HYPO_DIR).conflict) pushTarget = resolvePushTarget(HYPO_DIR);
       }
     },
     { timeoutMs: VAULT_LOCK_TIMEOUT_MS },
@@ -104,7 +167,14 @@ try {
   // 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.
+  // other step in this hook. `pushTarget` is still null here, so a lock
+  // we never took can never turn into a push.
 }
 
+// Outside the lock on purpose: see the note above the try block. Guarded by a
+// target resolved only after a successful commit and a non-conflicting pull,
+// so the set of cases that push is exactly the set that pushed before this
+// split, and what each one sends is fixed before the lock goes.
+if (pushTarget) pushRemote(HYPO_DIR, pushTarget);
+
 console.log(JSON.stringify({ continue: true, suppressOutput: true }));

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

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 /**
- * hypo-auto-minimal-crystallize.mjs — Stop hook (Layer 3)
+ * hypo-auto-minimal-crystallize.mjs: Stop chain stage 4, last (Layer 3)
+ *
+ * Spawned by hypo-stop.mjs, which is the only Stop registration. This stage runs
+ * last on purpose: it is the only one that can emit `decision: "block"`, and its
+ * close gate reads the committed state stage 3 (hypo-auto-commit) produced.
  *
  * Last hook in the Stop chain: a final-line defense that blocks `Stop` when
  * the current session did substantial work (mutation, or a high-volume
@@ -17,8 +21,19 @@
  *        calls (Read/Grep/Glob/Bash) — 6a, so read-only review/debug sessions
  *        are also nudged to close. Pure Q&A / incidental lookups still skip.
  *   4. no recent user close-intent → continue       (close-intent gate, see below)
- *   5. readSessionClosedMarker(session_id) valid
- *                                  → continue       (close already verified)
+ *   5. close verdict for session_id, closeCheckpointState (close-receipt.mjs):
+ *        a. closed: valid receipt + a marker naming its generation
+ *                                               → continue (cwd/log-only exemption unchanged)
+ *        b. legacy-closed: no receipt, marker with NO receiptGeneration
+ *                                               → continue (marker's own 7-day TTL)
+ *        c. broken: receipt and marker disagree (a marker promising a missing,
+ *           invalid or different receipt, or a valid receipt with no marker or
+ *           a mismatched one)                  → fall through to block, naming why
+ *        d. open: neither                       → fall through to block
+ *      A valid receipt only certifies the files it names (the checkpoint
+ *      contract), so branch (a) also fires an unresolved-changes
+ *      systemMessage once per receipt generation (see notifyUnresolved).
+ *      This is never a block, only a notice riding along on the continue reply.
  *   6. otherwise                   → decision:block
  *
  * Close-intent gate (added after PR-C dogfooding revealed every-turn block —
@@ -55,13 +70,12 @@
  * mode the per-session marker was introduced to prevent.
  */
 
-import { existsSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
 import {
   HYPO_DIR,
   PKG_ROOT,
   isSubstantialSession,
-  readSessionClosedMarker,
   extractUserMessages,
   isClosePattern,
   isGateSkipped,
@@ -70,10 +84,72 @@ import {
   isCloseReconfirmDeclined,
   CLOSE_RECONFIRM_MARK,
   resolveGateProjectOverride,
+  gitDirtyFiles,
 } from './hypo-shared.mjs';
+import { closeCheckpointState, isCloseComplete, receiptPath } from './close-receipt.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+
+// Carrying a systemMessage does not turn this into a block: the session is
+// still free to end, the message just rides along on the same continue reply
+// (hooks/hypo-stop.mjs merges every stage's systemMessage into one).
+function emitContinue(systemMessage) {
+  const out = { continue: true, suppressOutput: !systemMessage };
+  if (systemMessage) out.systemMessage = systemMessage;
+  console.log(JSON.stringify(out));
+}
 
-function emitContinue() {
-  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+// The checkpoint contract: a valid receipt proves only the files it names were
+// committed at the receipt's commit, never that the rest of the session's work
+// was saved, and never that a named file still has those bytes. Every dirty
+// path is unresolved: a path outside the receipt's entries was never certified,
+// and a path inside them differs from HEAD now, so the bytes on disk are
+// committed nowhere (the receipt's commit is an ancestor of HEAD). The second
+// kind is listed apart as changed after the close checkpoint. The notice fires
+// once per receipt generation, or again once the dirty list itself changes,
+// never on every Stop turn a long session produces. State lives next to the
+// receipt it is keyed to (`.cache/sessions/<sid>/`), so an invalidated or
+// replaced receipt (a fresh close attempt) starts this notice fresh too.
+function notifyUnresolved(hypoDir, sessionId, receipt) {
+  const certified = new Set((receipt.entries || []).map((e) => e && e.path));
+  const dirty = gitDirtyFiles(hypoDir).sort();
+  if (dirty.length === 0) return null;
+  const rp = receiptPath(hypoDir, sessionId);
+  if (!rp) return null;
+  const notifyPath = join(dirname(rp), 'unresolved-notified.json');
+  let prior = null;
+  try {
+    prior = JSON.parse(readFileSync(notifyPath, 'utf-8'));
+  } catch {
+    prior = null;
+  }
+  const sameList =
+    prior &&
+    prior.generation === receipt.generation &&
+    Array.isArray(prior.files) &&
+    prior.files.length === dirty.length &&
+    prior.files.every((f, i) => f === dirty[i]);
+  if (sameList) return null;
+  try {
+    atomicWrite(notifyPath, JSON.stringify({ generation: receipt.generation, files: dirty }));
+  } catch {
+    // Best-effort: a failed write only means this same notice repeats next
+    // turn, never that it silently stops appearing.
+  }
+  const uncertified = dirty.filter((f) => !certified.has(f));
+  const changedAfter = dirty.filter((f) => certified.has(f));
+  const parts = [];
+  if (uncertified.length > 0) parts.push(uncertified.join(', '));
+  if (changedAfter.length > 0) {
+    // No ownership test here: a shared append target such as log.md is in
+    // nearly every receipt, and another session's append makes it dirty too.
+    parts.push(
+      `[close 체크포인트 뒤 바뀜(이 세션 또는 다른 세션), 지금 내용은 커밋되지 않음: ${changedAfter.join(', ')}]`,
+    );
+  }
+  return (
+    `[WIKI_AUTOCLOSE] close checkpoint 확인됨 (session_id=${sessionId}). 다만 이 체크포인트가 ` +
+    `증명하지 않는 미해결 변경이 있습니다: ${parts.join(' ')}`
+  );
 }
 
 function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
@@ -92,6 +168,12 @@ function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
   // label can't drift out of sync silently. The decline label ("아직, 계속")
   // stays a literal here — it is matched by the tolerant DECLINE regex in
   // isCloseReconfirmDeclined, not by an exact-mark check.
+  // A broken checkpoint (receipt and marker disagree) is not "never closed":
+  // say so, whichever wording the block takes, so the rerun is understood as
+  // re-issuing both artifacts rather than as a first close.
+  const brokenNote = opts.brokenReason
+    ? ` 이전 close 체크포인트가 깨져 있어 완료로 보지 않았습니다: ${opts.brokenReason}. close 를 다시 실행하면 영수증과 마커를 함께 새로 씁니다. --mark-session-closed 가 prior-checkpoint-rewritten 으로 거부되면 이전 close 가 증명한 커밋이 히스토리에서 사라진 것이니, 그 커밋을 되살리거나 사용자에게 다시 close 를 요청받아 /hypo:crystallize 로 새 close 를 적용하세요.`
+    : '';
   if (opts.reconfirm) {
     console.log(
       JSON.stringify({
@@ -102,7 +184,8 @@ function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
           `임의로 닫지 말고 AskUserQuestion으로 사용자에게 지금 세션을 닫을지 물어보세요. ` +
           `선택지는 "${CLOSE_RECONFIRM_MARK}"와 "아직, 계속"으로 제시합니다. 사용자가 ` +
           `"${CLOSE_RECONFIRM_MARK}"를 고른 뒤에만 세션 마무리를 진행하세요. 그전에는 ` +
-          `마커를 쓰거나 종료 명령을 실행하지 마세요.`,
+          `마커를 쓰거나 종료 명령을 실행하지 마세요.` +
+          brokenNote,
         stopReason: 'session-close incomplete (Layer 3, reconfirm)',
       }),
     );
@@ -172,7 +255,7 @@ function emitBlock(sessionId, transcriptPath, gate = null, opts = {}) {
   console.log(
     JSON.stringify({
       decision: 'block',
-      reason,
+      reason: reason + brokenNote,
       stopReason: 'session-close incomplete (Layer 3)',
     }),
   );
@@ -244,6 +327,10 @@ process.stdin.on('end', () => {
     // (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;
+    // This session's close verdict (step 5), read once and shared with the
+    // gate so its log-only and attribution reading uses the same marker Stop
+    // judged, never one the verdict rejected.
+    let checkpoint = null;
     const computeGate = () => {
       try {
         // resolveGateProjectOverride (session-close-scope-boundary spec §2/§3): Stop
@@ -258,6 +345,9 @@ process.stdin.on('end', () => {
           ...(transcriptPath ? { transcriptPath } : {}),
           ...(sessionCwd ? { sessionCwd } : {}),
           ...(sessionId ? { sessionId } : {}),
+          ...(checkpoint
+            ? { closeMarker: isCloseComplete(checkpoint) ? checkpoint.marker : null }
+            : {}),
           ...(attributionScope ? { attributionScope } : {}),
         });
       } catch {
@@ -265,28 +355,38 @@ process.stdin.on('end', () => {
       }
     };
 
-    // 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).
+    // 5. close verdict for this session_id (order in the file header), from
+    // closeCheckpointState, the same verdict check, doctor and PreCompact use.
+    // A finished close only attests the project(s)/scope it recorded: if THIS
+    // session's cwd project still has an unstarted close, honoring it would end
+    // the session green while that project stays open (the session-cwd
+    // false-green), so the cwd re-check below still runs. A broken checkpoint
+    // (receipt and marker disagree) falls through to block and says why.
+    let brokenReason = null;
     if (sessionId) {
-      const marker = readSessionClosedMarker(HYPO_DIR, sessionId);
-      if (marker) {
-        if (marker.scope === 'log-only' || !sessionCwd) {
-          emitContinue();
+      checkpoint = closeCheckpointState(HYPO_DIR, sessionId);
+      if (isCloseComplete(checkpoint)) {
+        const { receipt, marker } = checkpoint;
+        // A legacy close has no receipt, so no certified file list to compare
+        // the dirty tree against: no unresolved-changes notice, same as before.
+        const notice = () => (receipt ? notifyUnresolved(HYPO_DIR, sessionId, receipt) : undefined);
+        const isLogOnly = receipt
+          ? receipt.scope?.mode === 'log-only'
+          : marker.scope === 'log-only';
+        if (isLogOnly || !sessionCwd) {
+          emitContinue(notice());
           return;
         }
         gate = computeGate();
         const cwdBlocked = !!gate?.blockers?.some((b) => b.type === 'close-cwd');
         if (!cwdBlocked) {
-          emitContinue();
+          emitContinue(notice());
           return;
         }
-        // marker present but the session's cwd project close is incomplete: fall
-        // through to block, reusing the gate computed above.
+        // finished close, but the session's cwd project close is incomplete:
+        // fall through to block, reusing the gate computed above.
+      } else if (checkpoint.state === 'broken') {
+        brokenReason = checkpoint.reason;
       }
     }
 
@@ -322,7 +422,11 @@ process.stdin.on('end', () => {
       return;
     }
 
-    emitBlock(sessionId, transcriptPath, gate, { reconfirm: workIncomplete, sessionCwd });
+    emitBlock(sessionId, transcriptPath, gate, {
+      reconfirm: workIncomplete,
+      sessionCwd,
+      brokenReason,
+    });
   } 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

@@ -48,7 +48,19 @@ if (filePath.startsWith(HYPO_DIR + '/') || filePath === HYPO_DIR) {
     // 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);
+    const recorded = recordTouchedPaths(HYPO_DIR, input.session_id, rel);
+    if (!recorded) {
+      // A lock-timeout or write failure here leaves the file just written
+      // with nothing in ANY session's touched-paths set to bring it into an
+      // auto-commit: it sits dirty until an unrelated later write to the
+      // same path happens to succeed. This hook's stdout is not suppressed
+      // wholesale like the Stop hooks, but its own output is a fixed
+      // continue/suppressOutput payload below, so stderr is the only channel
+      // available to surface this.
+      process.stderr.write(
+        `[hypo-auto-stage] ${rel} 를 이번 세션의 커밋 범위에 기록하지 못했습니다\n`,
+      );
+    }
 
     // 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

package/hooks/hypo-close-guard.mjs

@@ -32,7 +32,8 @@
  *
  * 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
+ * then CLEARS a session's touched-paths set every time Stop runs (only a
+ * path `.hypoignore` keeps out of the commit stays). 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

package/hooks/hypo-cwd-change.mjs

@@ -2,8 +2,12 @@
 /**
  * hypo-cwd-change.mjs — CwdChanged hook
  *
- * When the working directory changes mid-session, re-inject the matching
- * project hot.md. Skips if still within the same project subtree.
+ * When the working directory changes mid-session, display a notification for
+ * the matching project hot.md. Tracing the installed binary (Claude Code
+ * 2.1.276, reconfirmed on 2.1.283) shows the `systemMessage` this hook emits
+ * does not reach the model, only a 5-second terminal toast, so "re-inject"
+ * overstates what this hook can actually do. Skips if still within the same
+ * project subtree.
  */
 
 import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
@@ -32,8 +36,8 @@ const PROJECTS_DIR = join(HYPO_DIR, 'projects');
 const GLOBAL_HOT = join(HYPO_DIR, 'hot.md');
 const MAX_CHARS = 3000;
 
-// Privacy guard: a .hypoignore-matched hot.md must not be
-// re-emitted into additionalContext on cwd change.
+// Privacy guard: a .hypoignore-matched hot.md must not be re-emitted in this
+// hook's output on cwd change, whichever field carries it.
 //
 // 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
@@ -98,7 +102,7 @@ process.stdin.on('end', () => {
     const oldCwd = data.old_cwd || data.old_directory || data.previous_cwd || '';
     const sessionId = data.session_id || 'default';
 
-    // Skip re-injection if still in the same project
+    // Skip re-notifying if still in the same project
     const oldHit = oldCwd ? findProjectHot(oldCwd) : null;
     const newHit = findProjectHot(newCwd);
 
@@ -109,13 +113,13 @@ process.stdin.on('end', () => {
 
     const ignorePatterns = loadHypoIgnore(HYPO_DIR);
 
-    // This injection is not a licensing surface for the observed-set gate
-    // (see base-store.mjs's recordObserved): a session's tracked
+    // Reading this hot.md is not a licensing surface for the observed-set
+    // gate (see base-store.mjs's recordObserved): a session's tracked
     // `targets` are fixed at whichever project the OWNING SessionStart hit,
     // and a cwd move can land here in a different project entirely, so
     // recording an observation against this read could credit a path outside
     // that fixed target set. Nothing here calls recordObserved; the guard
-    // stays exactly as conservative for a cwd-change injection as it was
+    // stays exactly as conservative for a cwd-change notice as it was
     // before the observed set existed.
     if (newHit) {
       const fromFile = readIfNotIgnored(newHit.hotPath, ignorePatterns);
@@ -125,10 +129,12 @@ process.stdin.on('end', () => {
           ? '(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
-      // missing or .hypoignore'd (fromFile null), there is nothing for the LLM
-      // to summarize, so forcing "Resuming" would be empty noise.
+      // hypo-first-prompt, which forces Claude's reply to lead with a
+      // "Resuming <project>" line, verbatim rather than a content summary
+      // (see hypo-first-prompt.mjs's cwdMove branch). Only arm when real hot
+      // content was actually found; if hot.md is missing or .hypoignore'd
+      // (fromFile null), there is no snapshot to resume from, so claiming
+      // "Resuming" would be false.
       if (fromFile) {
         try {
           writeFileSync(
@@ -152,16 +158,35 @@ process.stdin.on('end', () => {
       // working_dir distinct from the vault, surface where wiki files live.
       const vaultOrientation = buildVaultOrientation(newCwd);
       const orientPrefix = vaultOrientation ? `${vaultOrientation}\n\n` : '';
-      // Built inline rather than through buildOutput(): CwdChanged has no
-      // documented context-injection path, so the nested hookSpecificOutput
-      // shape buildOutput() now emits would be wrong for this event. The
-      // follow-up that moves this hook to systemMessage removes these three
-      // literals; until then they keep today's behaviour unchanged.
+      // Built inline rather than through buildOutput(): the hook reference's
+      // CwdChanged section documents watchPaths and systemMessage as the
+      // fields Claude Code reads from that event's output, and neither is an
+      // additionalContext path, so there is no additionalContext path here.
+      // CwdChanged and FileChanged each get their own section and each repeats
+      // this sentence, so the two are not sharing one paragraph (checked
+      // against the published reference 2026-09-21). The notice rides
+      // systemMessage instead. The reference says systemMessage "shows the
+      // systemMessage as a brief terminal notification" and "doesn't reach
+      // the SDK message stream," but it does not say whether systemMessage
+      // reaches the model on this event either way, so treat that as
+      // undocumented rather than denied. As of Claude Code 2.1.276 (checked
+      // 2026-09-18) and reconfirmed on 2.1.283, tracing the installed binary
+      // shows the only consumer of this systemMessage is the terminal
+      // notification queue: a low-priority toast (priority 'low', timeoutMs
+      // 5000, key 'env-hook') that a later same-keyed message replaces and
+      // that fades after five seconds, with no branch that forwards it to the
+      // model; outside the interactive REPL (SDK, headless) the injecting
+      // function is null, so the message is simply dropped. No live-session
+      // observation of this path exists either way. Until the documentation
+      // says otherwise, treat this event as not reaching the model.
+      // Whatever the documentation eventually says, the .hypoignore and
+      // visibility guards above run first, so a withheld page never reaches
+      // this line.
       console.log(
         JSON.stringify({
           continue: true,
           suppressOutput: true,
-          additionalContext: `${orientPrefix}[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
+          systemMessage: `${orientPrefix}[WIKI: cwd changed → project=${sanitizeProjForPrompt(newHit.proj)}]\n\n${content}`,
         }),
       );
       return;
@@ -202,7 +227,7 @@ process.stdin.on('end', () => {
           JSON.stringify({
             continue: true,
             suppressOutput: true,
-            additionalContext: suggestPrefix.trimEnd(),
+            systemMessage: suggestPrefix.trimEnd(),
           }),
         );
       } else {
@@ -214,7 +239,7 @@ process.stdin.on('end', () => {
       JSON.stringify({
         continue: true,
         suppressOutput: true,
-        additionalContext: `${suggestPrefix}[WIKI: cwd changed → no project match, injecting global hot]\n\n${globalContent}`,
+        systemMessage: `${suggestPrefix}[WIKI: cwd changed → no project match, global hot notice]\n\n${globalContent}`,
       }),
     );
   } catch (err) {

package/hooks/hypo-file-watch.mjs

@@ -2,8 +2,13 @@
 /**
  * hypo-file-watch.mjs — FileChanged hook
  *
- * When a hot.md inside the wiki is modified externally (e.g. by a remote
- * agent or another Claude Code session), re-inject its contents.
+ * When any file under HYPO_DIR changes, build a notification of its contents.
+ * FileChanged fires for edits from any source: Claude's own Write/Edit/Bash
+ * tools as well as an external process (a remote agent, another Claude Code
+ * session), not only external ones. Tracing the installed binary (Claude Code
+ * 2.1.276, reconfirmed on 2.1.283) shows that notification is a five-second
+ * terminal toast that does not reach the model, so this hook does not put
+ * anything back in front of the model, only the terminal.
  */
 
 import { readFileSync, existsSync } from 'fs';
@@ -36,9 +41,12 @@ process.stdin.on('end', () => {
       return;
     }
 
-    // Privacy guard: refuse to inject
-    // .hypoignore-matched paths. Without this, `.env*` or other secrets under
-    // HYPO_DIR are re-emitted as additionalContext to the Claude provider.
+    // Privacy guard: refuse to emit .hypoignore-matched paths. Without this,
+    // `.env*` or other secrets under HYPO_DIR are re-emitted in this hook's
+    // output. The guard does not depend on which field carries that output:
+    // whether or not the systemMessage terminal notification documented for
+    // FileChanged actually appears on a given machine is unmeasured, so the
+    // only safe assumption is that a matched path must never be put in it.
     const patterns = loadHypoIgnore(HYPO_DIR);
     if (patterns.length > 0 && isIgnored(filePath, HYPO_DIR, patterns)) {
       console.log(JSON.stringify({ continue: true, suppressOutput: true }));
@@ -65,11 +73,41 @@ process.stdin.on('end', () => {
     const content = fileRaw.slice(0, MAX_CHARS);
     const relPath = filePath.replace(HYPO_DIR + '/', '');
 
+    // Built inline rather than through buildOutput(): the hook reference's
+    // FileChanged section documents the same two fields as its CwdChanged
+    // section (watchPaths, systemMessage), and neither is an additionalContext
+    // path, so the notice rides systemMessage. The two events are documented
+    // separately, each repeating the sentence for itself (checked against the
+    // published reference 2026-09-21). The reference says systemMessage
+    // "shows the systemMessage as a brief terminal notification" and
+    // "doesn't reach the SDK message stream," but it does not say whether
+    // systemMessage reaches the model on this event either way. As of Claude
+    // Code 2.1.276 (checked 2026-09-18) and reconfirmed on 2.1.283, tracing
+    // the installed binary shows the same shared consumer as
+    // hypo-cwd-change.mjs: a low-priority terminal toast with no branch to
+    // the model, dropped entirely outside the interactive REPL. No
+    // live-session observation of this path exists either way. Until the
+    // documentation says otherwise, treat this event as not reaching the
+    // model.
+    // On a stock install this hook still has no registered trigger: its
+    // matcher is omitted (not blank), which the reference says matches every
+    // watched file while adding nothing to the watch list, and nothing in
+    // this package returns watchPaths to seed that list. The watch list is
+    // session-global though, not scoped to this plugin: if another hook or
+    // plugin seeds it, this matcher-less group fires on every watched file,
+    // not just wiki ones. The HYPO_DIR check above (`filePath.startsWith(HYPO_DIR
+    // + '/')`, a string-prefix test that does not resolve symlinks) still
+    // returns immediately for any path that does not start with HYPO_DIR, so
+    // a watch seeded elsewhere cannot point this hook at a path outside the
+    // wiki. A symlink living inside the wiki is a separate case: its path
+    // still starts with HYPO_DIR and passes the check above, but
+    // readFileSync follows it, so whatever that link points to, inside the
+    // wiki or not, is what actually gets emitted.
     console.log(
       JSON.stringify({
         continue: true,
         suppressOutput: true,
-        additionalContext: `[WIKI FILE UPDATED: ${relPath}]\n\n${content}`,
+        systemMessage: `[WIKI FILE UPDATED: ${relPath}]\n\n${content}`,
       }),
     );
   } catch (err) {