mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/tool-trace/writeSearch.ts

@@ -11,6 +11,7 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { slugify } from "../../utils/slug.js";
 import { toUtcIsoDate } from "../../utils/date.js";
+import { writeFileAtomic } from "../../utils/files/atomic.js";
 import { WORKSPACE_DIRS } from "../paths.js";
 
 export const SEARCHES_DIR = WORKSPACE_DIRS.searches;
@@ -87,7 +88,11 @@ const defaultDeps: WriteSearchDeps = {
   mkdir: async (dir) => {
     await fsp.mkdir(dir, { recursive: true });
   },
-  writeFile: (filePath, content) => fsp.writeFile(filePath, content, "utf-8"),
+  // Atomic write so a crash mid-flight can't leave a half-written
+  // search markdown that the jsonl `contentRef` then points at
+  // (#881 v2). Tests inject their own adapter so behaviour stays
+  // mockable.
+  writeFile: (filePath, content) => writeFileAtomic(filePath, content),
 };
 
 /**

package/server/workspace/wiki-backlinks/index.ts

@@ -21,6 +21,7 @@ import { workspacePath as defaultWorkspacePath } from "../workspace.js";
 import { WORKSPACE_DIRS } from "../paths.js";
 import { log } from "../../system/logger/index.js";
 import { updateSessionBacklinks } from "./sessionBacklinks.js";
+import { writeWikiPage } from "../wiki-pages/io.js";
 import { ONE_SECOND_MS } from "../../utils/time.js";
 
 // Small tolerance for filesystem mtime granularity (some filesystems
@@ -35,12 +36,23 @@ export interface WikiBacklinksDeps {
   writeFile: (filePath: string, content: string) => Promise<void>;
 }
 
-const defaultDeps: WikiBacklinksDeps = {
-  readdir: (dir) => fsp.readdir(dir),
-  stat: (filePath) => fsp.stat(filePath),
-  readFile: (filePath) => fsp.readFile(filePath, "utf-8"),
-  writeFile: (filePath, content) => fsp.writeFile(filePath, content, "utf-8"),
-};
+// Default writers funnel through `writeWikiPage` so the backlink
+// append participates in the same atomic-write + history pipeline
+// as user / LLM edits. Pre-#763 this was a non-atomic
+// `fsp.writeFile` and the call could leave a half-written page on
+// crash. Editor identity is `"system"` so PR 2's snapshot view can
+// distinguish automated edits from human / LLM ones.
+function buildDefaultDeps(workspaceRoot: string, sessionId: string): WikiBacklinksDeps {
+  return {
+    readdir: (dir) => fsp.readdir(dir),
+    stat: (filePath) => fsp.stat(filePath),
+    readFile: (filePath) => fsp.readFile(filePath, "utf-8"),
+    writeFile: async (filePath, content) => {
+      const slug = path.basename(filePath, ".md");
+      await writeWikiPage(slug, content, { editor: "system", sessionId }, { workspaceRoot });
+    },
+  };
+}
 
 export interface MaybeAppendWikiBacklinksOptions {
   chatSessionId: string;
@@ -52,7 +64,7 @@ export interface MaybeAppendWikiBacklinksOptions {
 export async function maybeAppendWikiBacklinks(opts: MaybeAppendWikiBacklinksOptions): Promise<void> {
   if (!opts.chatSessionId) return;
   const workspaceRoot = opts.workspaceRoot ?? defaultWorkspacePath;
-  const deps: WikiBacklinksDeps = { ...defaultDeps, ...(opts.deps ?? {}) };
+  const deps: WikiBacklinksDeps = { ...buildDefaultDeps(workspaceRoot, opts.chatSessionId), ...(opts.deps ?? {}) };
   const pagesDir = path.join(workspaceRoot, WORKSPACE_DIRS.wikiPages);
 
   const files = await listPageFiles(pagesDir, deps);

package/server/workspace/wiki-backlinks/sessionBacklinks.ts

@@ -113,6 +113,7 @@ function extractSessionIdFromHref(href: string): string | null {
 function stripFragmentAndQuery(href: string): string {
   let end = href.length;
   const hash = href.indexOf("#");
+  // eslint-disable-next-line security/detect-possible-timing-attacks -- numeric indexOf check, not a credential compare
   if (hash !== -1) end = hash;
   const query = href.indexOf("?");
   if (query !== -1 && query < end) end = query;

package/server/workspace/wiki-history/hook/snapshot.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+// server/workspace/wiki-history/hook/snapshot.ts
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path2 from "node:path";
+
+// src/lib/wiki-page/slug.ts
+import path from "node:path";
+function isSafeSlug(slug) {
+  if (slug.length === 0) return false;
+  if (slug === "." || slug === "..") return false;
+  if (slug.includes("/") || slug.includes("\\")) return false;
+  if (slug.includes("\0")) return false;
+  return true;
+}
+function wikiSlugFromAbsPath(absPath, pagesDir) {
+  const rel = path.relative(pagesDir, absPath);
+  if (rel.length === 0) return null;
+  if (path.isAbsolute(rel)) return null;
+  if (rel.includes(path.sep)) return null;
+  if (!rel.endsWith(".md")) return null;
+  const slug = rel.slice(0, -".md".length);
+  if (!isSafeSlug(slug)) return null;
+  return slug;
+}
+
+// server/workspace/wiki-history/hook/snapshot.ts
+var WORKSPACE_ROOT = path2.join(homedir(), "mulmoclaude");
+var WIKI_PAGES_DIR = path2.join(WORKSPACE_ROOT, "data", "wiki", "pages");
+var TOKEN_PATH = path2.join(WORKSPACE_ROOT, ".session-token");
+var PORT_PATH = path2.join(WORKSPACE_ROOT, ".server-port");
+var SERVER_HOST = process.env.MULMOCLAUDE_HOST ?? "127.0.0.1";
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function extractFilePath(payload) {
+  const fromInput = payload.tool_input?.file_path;
+  if (typeof fromInput === "string") return fromInput;
+  const fromResponse = payload.tool_response?.filePath;
+  if (typeof fromResponse === "string") return fromResponse;
+  return null;
+}
+function readTokenSafe() {
+  try {
+    return readFileSync(TOKEN_PATH, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+function readPortSafe() {
+  try {
+    const raw = readFileSync(PORT_PATH, "utf-8").trim();
+    const port = Number.parseInt(raw, 10);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const payload = await readStdin();
+  if (!payload) return;
+  const filePath = extractFilePath(payload);
+  if (!filePath) return;
+  const slug = wikiSlugFromAbsPath(filePath, WIKI_PAGES_DIR);
+  if (slug === null) return;
+  const token = readTokenSafe();
+  const port = readPortSafe();
+  if (!token || port === null) return;
+  const envChatSessionId = process.env.MULMOCLAUDE_CHAT_SESSION_ID;
+  const payloadSessionId = typeof payload.session_id === "string" && payload.session_id.length > 0 ? payload.session_id : void 0;
+  const sessionId = envChatSessionId && envChatSessionId.length > 0 ? envChatSessionId : payloadSessionId;
+  const body = sessionId === void 0 ? { slug } : { slug, sessionId };
+  try {
+    await fetch(`http://${SERVER_HOST}:${port}/api/wiki/internal/snapshot`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify(body)
+    });
+  } catch {
+  }
+}
+main().catch(() => {
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsic25hcHNob3QudHMiLCAiLi4vLi4vLi4vLi4vc3JjL2xpYi93aWtpLXBhZ2Uvc2x1Zy50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLy8gUG9zdFRvb2xVc2UgaG9vayBzb3VyY2UgXHUyMDE0IHJ1bnMgYWZ0ZXIgZXZlcnkgQ2xhdWRlIENMSSBXcml0ZSAvXG4vLyBFZGl0IHRvb2wgY2FsbC4gRGV0ZWN0cyB3cml0ZXMgdGhhdCB0YXJnZXQgYSB3aWtpIHBhZ2UgZmlsZVxuLy8gYW5kIFBPU1RzIGB7IHNsdWcsIHNlc3Npb25JZD8gfWAgdG8gdGhlIHBhcmVudCBzZXJ2ZXInc1xuLy8gYC9hcGkvd2lraS9pbnRlcm5hbC9zbmFwc2hvdGAgZW5kcG9pbnQgc28gdGhlIHNuYXBzaG90IHBpcGVsaW5lXG4vLyAoIzc2MyBQUiAyKSByZWNvcmRzIHRoZSBuZXcgc3RhdGUuXG4vL1xuLy8gVEhJUyBGSUxFIElTIFRIRSBTT1VSQ0UgT0YgVFJVVEguIEVkaXRzIGhlcmUsIHRoZW4gcnVuXG4vLyBgeWFybiBidWlsZDpob29rc2AgKG9yIGB5YXJuIGJ1aWxkYCkgdG8gcmVnZW5lcmF0ZVxuLy8gYC4vc25hcHNob3QubWpzYC4gVGhlIGJ1bmRsZWQgYC5tanNgIGlzIGNvbW1pdHRlZCB0byBnaXQgc29cbi8vIGBwcm92aXNpb24udHNgIGNhbiByZWFkIGl0IGF0IHNlcnZlciBzdGFydHVwIHdpdGhvdXQgaW52b2tpbmdcbi8vIGVzYnVpbGQgb24gdGhlIHJ1bnRpbWUgcGF0aC4gQ0kgcnVucyBgeWFybiBidWlsZDpob29rcyAmJlxuLy8gZ2l0IGRpZmYgLS1leGl0LWNvZGVgIHRvIGNhdGNoIGEgc3RhbGUgYnVuZGxlLlxuLy9cbi8vIFRoZSBob29rIGV4ZWN1dGVzIGluc2lkZSBDbGF1ZGUgQ0xJJ3MgcHJvY2VzcyBzcGFjZSBcdTIwMTQgbXVzdCBiZVxuLy8gc2VsZi1jb250YWluZWQgRVNNLiBlc2J1aWxkIGJ1bmRsZXMgaW1wb3J0cyBmcm9tIHRoZSBzaGFyZWRcbi8vIGBzcmMvbGliL3dpa2ktcGFnZS9zbHVnLnRzYCBtb2R1bGUgc28gdGhlIGhvb2sgYW5kIHRoZVxuLy8gc2VydmVyLXNpZGUgYGNsYXNzaWZ5QXNXaWtpUGFnZWAgYWdyZWUgb24gd2hhdCBjb3VudHMgYXMgYVxuLy8gd2lraSBwYWdlIChubyBjb3B5LXBhc3RlIGRyaWZ0KS5cblxuaW1wb3J0IHsgcmVhZEZpbGVTeW5jIH0gZnJvbSBcIm5vZGU6ZnNcIjtcbmltcG9ydCB7IGhvbWVkaXIgfSBmcm9tIFwibm9kZTpvc1wiO1xuaW1wb3J0IHBhdGggZnJvbSBcIm5vZGU6cGF0aFwiO1xuaW1wb3J0IHsgd2lraVNsdWdGcm9tQWJzUGF0aCB9IGZyb20gXCIuLi8uLi8uLi8uLi9zcmMvbGliL3dpa2ktcGFnZS9zbHVnLmpzXCI7XG5cbi8vIFdvcmtzcGFjZSBsYXlvdXQgbWF0Y2hlcyBgV09SS1NQQUNFX0RJUlMud2lraVBhZ2VzYC4gV2UgaGFyZC1cbi8vIGNvZGUgXCJkYXRhL3dpa2kvcGFnZXNcIiByYXRoZXIgdGhhbiBpbXBvcnRpbmcgdGhlIGNvbnN0YW50c1xuLy8gYmVjYXVzZSB0aGUgaG9vayBuZWVkcyB0byBzdGF5IGluZGVwZW5kZW50IG9mIHRoZSBzZXJ2ZXInc1xuLy8gcnVudGltZSBjb25maWcgXHUyMDE0IHRoZSBidW5kbGUgbXVzdCB3b3JrIGV2ZW4gd2hlbiB0aGUgc2VydmVyXG4vLyBwcm9jZXNzIGlzbid0IHJ1bm5pbmcgeWV0IChlLmcuIGR1cmluZyBhIHN0YXJ0dXAgcmFjZSkuXG5jb25zdCBXT1JLU1BBQ0VfUk9PVCA9IHBhdGguam9pbihob21lZGlyKCksIFwibXVsbW9jbGF1ZGVcIik7XG5jb25zdCBXSUtJX1BBR0VTX0RJUiA9IHBhdGguam9pbihXT1JLU1BBQ0VfUk9PVCwgXCJkYXRhXCIsIFwid2lraVwiLCBcInBhZ2VzXCIpO1xuY29uc3QgVE9LRU5fUEFUSCA9IHBhdGguam9pbihXT1JLU1BBQ0VfUk9PVCwgXCIuc2Vzc2lvbi10b2tlblwiKTtcbmNvbnN0IFBPUlRfUEFUSCA9IHBhdGguam9pbihXT1JLU1BBQ0VfUk9PVCwgXCIuc2VydmVyLXBvcnRcIik7XG4vLyBJbiBEb2NrZXIgbW9kZSB0aGUgcGFyZW50IHNlcnZlciBydW5zIG9uIHRoZSBob3N0J3MgMTI3LjAuMC4xXG4vLyB3aGljaCB0aGUgY29udGFpbmVyIGNhbid0IHJlYWNoIHZpYSBwbGFpbiBsb29wYmFjay4gVGhlIERvY2tlclxuLy8gc3Bhd24gcGx1bWJpbmcgc2V0cyBNVUxNT0NMQVVERV9IT1NUPWhvc3QuZG9ja2VyLmludGVybmFsIHNvXG4vLyBmZXRjaCgpIHJlc29sdmVzIHRvIHRoZSBob3N0IHNlcnZlci4gT3V0c2lkZSBEb2NrZXIgKG9yIHdoZW5cbi8vIHRoZSB2YXIgaXMgdW5zZXQpIHdlIGZhbGwgYmFjayB0byB0aGUgbG9vcGJhY2sgYWRkcmVzcy5cbmNvbnN0IFNFUlZFUl9IT1NUID0gcHJvY2Vzcy5lbnYuTVVMTU9DTEFVREVfSE9TVCA/PyBcIjEyNy4wLjAuMVwiO1xuXG5pbnRlcmZhY2UgSG9va1BheWxvYWQge1xuICB0b29sX2lucHV0PzogeyBmaWxlX3BhdGg/OiB1bmtub3duIH07XG4gIHRvb2xfcmVzcG9uc2U/OiB7IGZpbGVQYXRoPzogdW5rbm93biB9O1xuICBzZXNzaW9uX2lkPzogdW5rbm93bjtcbn1cblxuYXN5bmMgZnVuY3Rpb24gcmVhZFN0ZGluKCk6IFByb21pc2U8SG9va1BheWxvYWQgfCBudWxsPiB7XG4gIGNvbnN0IGNodW5rczogQnVmZmVyW10gPSBbXTtcbiAgZm9yIGF3YWl0IChjb25zdCBjaHVuayBvZiBwcm9jZXNzLnN0ZGluKSB7XG4gICAgY2h1bmtzLnB1c2godHlwZW9mIGNodW5rID09PSBcInN0cmluZ1wiID8gQnVmZmVyLmZyb20oY2h1bmspIDogY2h1bmspO1xuICB9XG4gIGNvbnN0IHJhdyA9IEJ1ZmZlci5jb25jYXQoY2h1bmtzKS50b1N0cmluZyhcInV0Zi04XCIpO1xuICBpZiAoIXJhdy50cmltKCkpIHJldHVybiBudWxsO1xuICB0cnkge1xuICAgIHJldHVybiBKU09OLnBhcnNlKHJhdykgYXMgSG9va1BheWxvYWQ7XG4gIH0gY2F0Y2gge1xuICAgIHJldHVybiBudWxsO1xuICB9XG59XG5cbmZ1bmN0aW9uIGV4dHJhY3RGaWxlUGF0aChwYXlsb2FkOiBIb29rUGF5bG9hZCk6IHN0cmluZyB8IG51bGwge1xuICAvLyBDbGF1ZGUgQ0xJIGhvb2sgcGF5bG9hZDogeyB0b29sX25hbWUsIHRvb2xfaW5wdXQsIHRvb2xfcmVzcG9uc2UsIC4uLiB9XG4gIC8vIERpZmZlcmVudCB0b29scyBzdXJmYWNlIHRoZSBwYXRoIHVuZGVyIGRpZmZlcmVudCBrZXlzIFx1MjAxNFxuICAvLyBjaGVjayBib3RoIHNoYXBlcyBkZWZlbnNpdmVseS5cbiAgY29uc3QgZnJvbUlucHV0ID0gcGF5bG9hZC50b29sX2lucHV0Py5maWxlX3BhdGg7XG4gIGlmICh0eXBlb2YgZnJvbUlucHV0ID09PSBcInN0cmluZ1wiKSByZXR1cm4gZnJvbUlucHV0O1xuICBjb25zdCBmcm9tUmVzcG9uc2UgPSBwYXlsb2FkLnRvb2xfcmVzcG9uc2U/LmZpbGVQYXRoO1xuICBpZiAodHlwZW9mIGZyb21SZXNwb25zZSA9PT0gXCJzdHJpbmdcIikgcmV0dXJuIGZyb21SZXNwb25zZTtcbiAgcmV0dXJuIG51bGw7XG59XG5cbmZ1bmN0aW9uIHJlYWRUb2tlblNhZmUoKTogc3RyaW5nIHtcbiAgdHJ5IHtcbiAgICByZXR1cm4gcmVhZEZpbGVTeW5jKFRPS0VOX1BBVEgsIFwidXRmLThcIikudHJpbSgpO1xuICB9IGNhdGNoIHtcbiAgICByZXR1cm4gXCJcIjtcbiAgfVxufVxuXG5mdW5jdGlvbiByZWFkUG9ydFNhZmUoKTogbnVtYmVyIHwgbnVsbCB7XG4gIHRyeSB7XG4gICAgY29uc3QgcmF3ID0gcmVhZEZpbGVTeW5jKFBPUlRfUEFUSCwgXCJ1dGYtOFwiKS50cmltKCk7XG4gICAgY29uc3QgcG9ydCA9IE51bWJlci5wYXJzZUludChyYXcsIDEwKTtcbiAgICByZXR1cm4gTnVtYmVyLmlzSW50ZWdlcihwb3J0KSAmJiBwb3J0ID4gMCAmJiBwb3J0IDwgNjU1MzYgPyBwb3J0IDogbnVsbDtcbiAgfSBjYXRjaCB7XG4gICAgcmV0dXJuIG51bGw7XG4gIH1cbn1cblxuYXN5bmMgZnVuY3Rpb24gbWFpbigpOiBQcm9taXNlPHZvaWQ+IHtcbiAgY29uc3QgcGF5bG9hZCA9IGF3YWl0IHJlYWRTdGRpbigpO1xuICBpZiAoIXBheWxvYWQpIHJldHVybjtcblxuICBjb25zdCBmaWxlUGF0aCA9IGV4dHJhY3RGaWxlUGF0aChwYXlsb2FkKTtcbiAgaWYgKCFmaWxlUGF0aCkgcmV0dXJuO1xuICBjb25zdCBzbHVnID0gd2lraVNsdWdGcm9tQWJzUGF0aChmaWxlUGF0aCwgV0lLSV9QQUdFU19ESVIpO1xuICBpZiAoc2x1ZyA9PT0gbnVsbCkgcmV0dXJuO1xuXG4gIGNvbnN0IHRva2VuID0gcmVhZFRva2VuU2FmZSgpO1xuICBjb25zdCBwb3J0ID0gcmVhZFBvcnRTYWZlKCk7XG4gIGlmICghdG9rZW4gfHwgcG9ydCA9PT0gbnVsbCkgcmV0dXJuOyAvLyBzZXJ2ZXIgaXNuJ3QgcmVhY2hhYmxlOyBzaWxlbnQgbm8tb3BcblxuICAvLyBQcmVmZXIgb3VyIGNoYXQtc2Vzc2lvbiBpZCBmcm9tIHRoZSBzcGF3biBlbnYgKCM5NjMpIFx1MjAxNCB0aGVcbiAgLy8gc2VydmVyJ3Mgc2Vzc2lvbiBzdG9yZSBrZXlzIGJ5IGNoYXRTZXNzaW9uSWQsIG5vdCBieSBDbGF1ZGVcbiAgLy8gQ0xJJ3MgaW50ZXJuYWwgc2Vzc2lvbl9pZCwgc28gdGhlIHRvb2xSZXN1bHQgcHVibGlzaCBvbiB0aGVcbiAgLy8gc2VydmVyIHNpZGUgb25seSBtYXRjaGVzIHdoZW4gd2UgZm9yd2FyZCBvdXIgb3duIGlkLiBGYWxsIGJhY2tcbiAgLy8gdG8gQ2xhdWRlIENMSSdzIGBzZXNzaW9uX2lkYCAoc3RpbGwgdXNlZnVsIGFzIGEgdHJhY2luZyB0b2tlblxuICAvLyBpbiB0aGUgc25hcHNob3QgZnJvbnRtYXR0ZXIpIHdoZW4gdGhlIGVudiB2YXIgaXMgYWJzZW50IFx1MjAxNCBlLmcuXG4gIC8vIGFuIG9sZGVyIG11bG1vY2xhdWRlIHNlcnZlciBzcGF3bmluZyBhIG5ld2VyIGhvb2sgYnVuZGxlLlxuICBjb25zdCBlbnZDaGF0U2Vzc2lvbklkID0gcHJvY2Vzcy5lbnYuTVVMTU9DTEFVREVfQ0hBVF9TRVNTSU9OX0lEO1xuICBjb25zdCBwYXlsb2FkU2Vzc2lvbklkID0gdHlwZW9mIHBheWxvYWQuc2Vzc2lvbl9pZCA9PT0gXCJzdHJpbmdcIiAmJiBwYXlsb2FkLnNlc3Npb25faWQubGVuZ3RoID4gMCA/IHBheWxvYWQuc2Vzc2lvbl9pZCA6IHVuZGVmaW5lZDtcbiAgY29uc3Qgc2Vzc2lvbklkID0gZW52Q2hhdFNlc3Npb25JZCAmJiBlbnZDaGF0U2Vzc2lvbklkLmxlbmd0aCA+IDAgPyBlbnZDaGF0U2Vzc2lvbklkIDogcGF5bG9hZFNlc3Npb25JZDtcbiAgY29uc3QgYm9keSA9IHNlc3Npb25JZCA9PT0gdW5kZWZpbmVkID8geyBzbHVnIH0gOiB7IHNsdWcsIHNlc3Npb25JZCB9O1xuXG4gIHRyeSB7XG4gICAgYXdhaXQgZmV0Y2goYGh0dHA6Ly8ke1NFUlZFUl9IT1NUfToke3BvcnR9L2FwaS93aWtpL2ludGVybmFsL3NuYXBzaG90YCwge1xuICAgICAgbWV0aG9kOiBcIlBPU1RcIixcbiAgICAgIGhlYWRlcnM6IHtcbiAgICAgICAgXCJDb250ZW50LVR5cGVcIjogXCJhcHBsaWNhdGlvbi9qc29uXCIsXG4gICAgICAgIEF1dGhvcml6YXRpb246IGBCZWFyZXIgJHt0b2tlbn1gLFxuICAgICAgfSxcbiAgICAgIGJvZHk6IEpTT04uc3RyaW5naWZ5KGJvZHkpLFxuICAgIH0pO1xuICB9IGNhdGNoIHtcbiAgICAvLyBOZXR3b3JrIC8gc2VydmVyIGRvd24gXHUyMDE0IGRyb3Agc2lsZW50bHkuIFRoZSB3aWtpIHBhZ2Ugd3JpdGVcbiAgICAvLyBpdHNlbGYgYWxyZWFkeSBzdWNjZWVkZWQ7IG1pc3Npbmcgb25lIHNuYXBzaG90IGlzIHJlY292ZXJhYmxlXG4gICAgLy8gKHRoZSBuZXh0IHNhdmUgd2lsbCByZWNvcmQgdGhlIG5leHQgc3RhdGUpLlxuICB9XG59XG5cbm1haW4oKS5jYXRjaCgoKSA9PiB7XG4gIC8vIEhvb2tzIHJ1biBzeW5jaHJvbm91c2x5IHRvIHRoZSBMTE0gdG9vbCBmbG93IFx1MjAxNCBuZXZlciB0aHJvdy5cbiAgLy8gQSBidXN0ZWQgaG9vayB3b3VsZCBtYWtlIGBXcml0ZWAgaXRzZWxmIGxvb2sgbGlrZSBpdCBmYWlsZWRcbiAgLy8gdG8gdGhlIExMTSwgd2hpY2ggaXMgbXVjaCB3b3JzZSB0aGFuIGEgbWlzc2luZyBzbmFwc2hvdC5cbn0pO1xuIiwgIi8vIFNoYXJlZCB3aWtpLXBhZ2Ugc2x1ZyBsb2dpYyBcdTIwMTQgcHVyZSBmdW5jdGlvbnMgcmV1c2VkIGJ5OlxuLy9cbi8vICAgLSBzZXJ2ZXIvd29ya3NwYWNlL3dpa2ktcGFnZXMvaW8udHMgKHRoZSB3cml0ZSBjaG9rZXBvaW50KVxuLy8gICAtIHNlcnZlci93b3Jrc3BhY2Uvd2lraS1oaXN0b3J5L2hvb2svc25hcHNob3QudHMgKHRoZVxuLy8gICAgIFBvc3RUb29sVXNlIGhvb2sgc2NyaXB0IHRoYXQgZGV0ZWN0cyBMTE0gV3JpdGUvRWRpdCBvbiBhXG4vLyAgICAgd2lraSBwYWdlIGFuZCB0cmlnZ2VycyBhIHNuYXBzaG90KVxuLy9cbi8vIEJvdGggY2FsbCBzaXRlcyBuZWVkIHRoZSBzYW1lIGFuc3dlcjogXCJnaXZlbiB0aGlzIGFic29sdXRlXG4vLyBwYXRoIGFuZCB0aGUgcGFnZXMgZGlyZWN0b3J5LCBpcyBpdCBhIHdpa2kgcGFnZSwgYW5kIGlmIHNvXG4vLyB3aGF0IHNsdWc/XCIuIEJlZm9yZSB0aGUgZXh0cmFjdGlvbiB0aGUgaG9vayByZS1pbXBsZW1lbnRlZFxuLy8gdGhlIHJ1bGVzIGFzIGEgSlMtYXMtc3RyaW5nIHRlbXBsYXRlIGxpdGVyYWwgdGhhdCBkcmlmdGVkXG4vLyBmcm9tIHRoZSBzZXJ2ZXItc2lkZSBsb2dpYyBcdTIwMTQgc2VlICM5NTEncyBkaXNjdXNzaW9uIG9mIGhvdyB0b1xuLy8gc3RvcCBjb3B5aW5nICNsaW50IGxvZ2ljIGJldHdlZW4gaG9vayBhbmQgc2VydmVyLlxuLy9cbi8vIE9ubHkgYG5vZGU6cGF0aGAgaXMgYWxsb3dlZCBoZXJlIHNvIGVzYnVpbGQgY2FuIGJ1bmRsZSB0aGlzXG4vLyBmaWxlIGludG8gdGhlIGhvb2sgc2NyaXB0IChubyBOb2RlLXNwZWNpZmljIHNlcnZlci1zaWRlXG4vLyBpbXBvcnRzIGxlYWsgaW50byB0aGUgYnVuZGxlKS5cblxuaW1wb3J0IHBhdGggZnJvbSBcIm5vZGU6cGF0aFwiO1xuXG4vKiogUmVqZWN0IHNsdWdzIHRoYXQgd291bGQgZXNjYXBlIGBkYXRhL3dpa2kvcGFnZXMvYCBvbmNlXG4gKiAgam9pbmVkIGJhY2sgaW50byBhIHBhdGgsIG9yIHRoYXQgYXJlIG90aGVyd2lzZSBpbnZhbGlkIGFzXG4gKiAgcGFnZSBmaWxlbmFtZXMuIFRoZSBjaG9rZXBvaW50IG11c3QgZGVmZW5kIGl0c2VsZiBldmVuIHdoZW5cbiAqICBjYWxsZXJzIGRlcml2ZSB0aGUgc2x1ZyBmcm9tIGEgdHJ1c3RlZCBzb3VyY2UgXHUyMDE0IGEgdHlwbyBvclxuICogIGZ1dHVyZSBjYWxsZXIgbWlzdGFrZSBzaG91bGQgZmFpbCBsb3VkLCBub3Qgc2lsZW50bHkgd3JpdGVcbiAqICBvdXRzaWRlIHRoZSB3aWtpIHRyZWUuXG4gKlxuICogIFRoZSBydWxlIGlzIGludGVudGlvbmFsbHkgbmFycm93IFx1MjAxNCBzZXBhcmF0b3JzIC8gYC4uYCAvIE5VTCAvXG4gKiAgZW1wdHkgXHUyMDE0IHNvIGl0IG9ubHkgcmVqZWN0cyB1bmFtYmlndW91cyB2aW9sYXRpb25zLiBBZXN0aGV0aWNcbiAqICBjb25jZXJucyAoZS5nLiBkb3QtcHJlZml4ZWQgZmlsZW5hbWVzKSBhcmUgb3V0IG9mIHNjb3BlOiBhXG4gKiAgcHJlLWV4aXN0aW5nIGBkYXRhL3dpa2kvcGFnZXMvLmZvby5tZGAgc2hvdWxkIHJlbWFpbiB3cml0YWJsZVxuICogIHRocm91Z2ggdGhlIGNob2tlcG9pbnQgKGNvZGV4IHJldmlldyBpdGVyLTIgIzg4MykuICovXG5leHBvcnQgZnVuY3Rpb24gaXNTYWZlU2x1ZyhzbHVnOiBzdHJpbmcpOiBib29sZWFuIHtcbiAgaWYgKHNsdWcubGVuZ3RoID09PSAwKSByZXR1cm4gZmFsc2U7XG4gIGlmIChzbHVnID09PSBcIi5cIiB8fCBzbHVnID09PSBcIi4uXCIpIHJldHVybiBmYWxzZTtcbiAgaWYgKHNsdWcuaW5jbHVkZXMoXCIvXCIpIHx8IHNsdWcuaW5jbHVkZXMoXCJcXFxcXCIpKSByZXR1cm4gZmFsc2U7XG4gIGlmIChzbHVnLmluY2x1ZGVzKFwiXFwwXCIpKSByZXR1cm4gZmFsc2U7XG4gIHJldHVybiB0cnVlO1xufVxuXG4vKiogR2l2ZW4gYW4gYWJzb2x1dGUgcGF0aCBhbmQgdGhlIGFic29sdXRlIGBwYWdlc0RpcmAsIHJldHVybiB0aGVcbiAqICBzbHVnIGlmIGBhYnNQYXRoYCBpcyBhIGRpcmVjdCBgLm1kYCBjaGlsZCBvZiBgcGFnZXNEaXJgLCBlbHNlXG4gKiAgbnVsbC4gUHVyZSBwYXRoLXN0cmluZyBtYXRoIFx1MjAxNCBubyBmcyBJTywgbm8gc3ltbGluayByZXNvbHV0aW9uLlxuICpcbiAqICBDYWxsZXIgcmVzcG9uc2liaWxpdHk6IHBhc3MgYWxyZWFkeS1yZWFscGF0aCdkIHZhbHVlcyBmb3IgYm90aFxuICogIGFyZ3VtZW50cy4gTWl4aW5nIGEgcmVhbHBhdGgnZCBgYWJzUGF0aGAgd2l0aCBhIHN5bWxpbmtlZFxuICogIGBwYWdlc0RpcmAgKG9yIHZpY2UgdmVyc2EpIHNpbGVudGx5IG1pc21hdGNoZXMgYmVjYXVzZVxuICogIGBwYXRoLnJlbGF0aXZlYCBpcyBwbGFpbiBzdHJpbmcgYXJpdGhtZXRpYy4gVGhlIHRyYXAgY2F1c2VkXG4gKiAgIzg4MyByZXZpZXctaXRlci0xIFx1MjAxNCBhIHN5bWxpbmtlZCB3b3Jrc3BhY2Ugc2lsZW50bHkgcm91dGVkXG4gKiAgd2lraSB3cml0ZXMgdGhyb3VnaCB0aGUgZ2VuZXJpYyB3cml0ZXIuICovXG5leHBvcnQgZnVuY3Rpb24gd2lraVNsdWdGcm9tQWJzUGF0aChhYnNQYXRoOiBzdHJpbmcsIHBhZ2VzRGlyOiBzdHJpbmcpOiBzdHJpbmcgfCBudWxsIHtcbiAgY29uc3QgcmVsID0gcGF0aC5yZWxhdGl2ZShwYWdlc0RpciwgYWJzUGF0aCk7XG4gIGlmIChyZWwubGVuZ3RoID09PSAwKSByZXR1cm4gbnVsbDtcbiAgaWYgKHBhdGguaXNBYnNvbHV0ZShyZWwpKSByZXR1cm4gbnVsbDtcbiAgLy8gRGlyZWN0IGNoaWxkIG9ubHkgXHUyMDE0IG5vIG5lc3RlZCBsYXlvdXQgdG9kYXkuIEFueSBzZXBhcmF0b3JcbiAgLy8gbWVhbnMgdGhlIHBhdGggZWl0aGVyIGVzY2FwZXMgKGAuLi9zZWNyZXQubWRgKSBvciBkZXNjZW5kc1xuICAvLyAoYHN1YmRpci9mb28ubWRgKS4gQSBsaXRlcmFsIHBhZ2UgbmFtZSBsaWtlIGAuLmZvby5tZGAgaXMgYVxuICAvLyBzaW5nbGUgc2VnbWVudCB3aXRob3V0IGEgc2VwYXJhdG9yIGFuZCBpcyBhbGxvd2VkIChjb2RleFxuICAvLyBpdGVyLTMgIzg4MyBcdTIwMTQgdGhlIHByaW9yIGBzdGFydHNXaXRoKFwiLi5cIilgIHJ1bGUgd3JvbmdseVxuICAvLyByZWplY3RlZCBpdCkuXG4gIGlmIChyZWwuaW5jbHVkZXMocGF0aC5zZXApKSByZXR1cm4gbnVsbDtcbiAgaWYgKCFyZWwuZW5kc1dpdGgoXCIubWRcIikpIHJldHVybiBudWxsO1xuICBjb25zdCBzbHVnID0gcmVsLnNsaWNlKDAsIC1cIi5tZFwiLmxlbmd0aCk7XG4gIGlmICghaXNTYWZlU2x1ZyhzbHVnKSkgcmV0dXJuIG51bGw7XG4gIHJldHVybiBzbHVnO1xufVxuIl0sCiAgIm1hcHBpbmdzIjogIjs7O0FBbUJBLFNBQVMsb0JBQW9CO0FBQzdCLFNBQVMsZUFBZTtBQUN4QixPQUFPQSxXQUFV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

package/server/workspace/wiki-history/hook/snapshot.ts

@@ -0,0 +1,135 @@
+// PostToolUse hook source — runs after every Claude CLI Write /
+// Edit tool call. Detects writes that target a wiki page file
+// and POSTs `{ slug, sessionId? }` to the parent server's
+// `/api/wiki/internal/snapshot` endpoint so the snapshot pipeline
+// (#763 PR 2) records the new state.
+//
+// THIS FILE IS THE SOURCE OF TRUTH. Edits here, then run
+// `yarn build:hooks` (or `yarn build`) to regenerate
+// `./snapshot.mjs`. The bundled `.mjs` is committed to git so
+// `provision.ts` can read it at server startup without invoking
+// esbuild on the runtime path. CI runs `yarn build:hooks &&
+// git diff --exit-code` to catch a stale bundle.
+//
+// The hook executes inside Claude CLI's process space — must be
+// self-contained ESM. esbuild bundles imports from the shared
+// `src/lib/wiki-page/slug.ts` module so the hook and the
+// server-side `classifyAsWikiPage` agree on what counts as a
+// wiki page (no copy-paste drift).
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { wikiSlugFromAbsPath } from "../../../../src/lib/wiki-page/slug.js";
+
+// Workspace layout matches `WORKSPACE_DIRS.wikiPages`. We hard-
+// code "data/wiki/pages" rather than importing the constants
+// because the hook needs to stay independent of the server's
+// runtime config — the bundle must work even when the server
+// process isn't running yet (e.g. during a startup race).
+const WORKSPACE_ROOT = path.join(homedir(), "mulmoclaude");
+const WIKI_PAGES_DIR = path.join(WORKSPACE_ROOT, "data", "wiki", "pages");
+const TOKEN_PATH = path.join(WORKSPACE_ROOT, ".session-token");
+const PORT_PATH = path.join(WORKSPACE_ROOT, ".server-port");
+// In Docker mode the parent server runs on the host's 127.0.0.1
+// which the container can't reach via plain loopback. The Docker
+// spawn plumbing sets MULMOCLAUDE_HOST=host.docker.internal so
+// fetch() resolves to the host server. Outside Docker (or when
+// the var is unset) we fall back to the loopback address.
+const SERVER_HOST = process.env.MULMOCLAUDE_HOST ?? "127.0.0.1";
+
+interface HookPayload {
+  tool_input?: { file_path?: unknown };
+  tool_response?: { filePath?: unknown };
+  session_id?: unknown;
+}
+
+async function readStdin(): Promise<HookPayload | null> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw.trim()) return null;
+  try {
+    return JSON.parse(raw) as HookPayload;
+  } catch {
+    return null;
+  }
+}
+
+function extractFilePath(payload: HookPayload): string | null {
+  // Claude CLI hook payload: { tool_name, tool_input, tool_response, ... }
+  // Different tools surface the path under different keys —
+  // check both shapes defensively.
+  const fromInput = payload.tool_input?.file_path;
+  if (typeof fromInput === "string") return fromInput;
+  const fromResponse = payload.tool_response?.filePath;
+  if (typeof fromResponse === "string") return fromResponse;
+  return null;
+}
+
+function readTokenSafe(): string {
+  try {
+    return readFileSync(TOKEN_PATH, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+
+function readPortSafe(): number | null {
+  try {
+    const raw = readFileSync(PORT_PATH, "utf-8").trim();
+    const port = Number.parseInt(raw, 10);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+async function main(): Promise<void> {
+  const payload = await readStdin();
+  if (!payload) return;
+
+  const filePath = extractFilePath(payload);
+  if (!filePath) return;
+  const slug = wikiSlugFromAbsPath(filePath, WIKI_PAGES_DIR);
+  if (slug === null) return;
+
+  const token = readTokenSafe();
+  const port = readPortSafe();
+  if (!token || port === null) return; // server isn't reachable; silent no-op
+
+  // Prefer our chat-session id from the spawn env (#963) — the
+  // server's session store keys by chatSessionId, not by Claude
+  // CLI's internal session_id, so the toolResult publish on the
+  // server side only matches when we forward our own id. Fall back
+  // to Claude CLI's `session_id` (still useful as a tracing token
+  // in the snapshot frontmatter) when the env var is absent — e.g.
+  // an older mulmoclaude server spawning a newer hook bundle.
+  const envChatSessionId = process.env.MULMOCLAUDE_CHAT_SESSION_ID;
+  const payloadSessionId = typeof payload.session_id === "string" && payload.session_id.length > 0 ? payload.session_id : undefined;
+  const sessionId = envChatSessionId && envChatSessionId.length > 0 ? envChatSessionId : payloadSessionId;
+  const body = sessionId === undefined ? { slug } : { slug, sessionId };
+
+  try {
+    await fetch(`http://${SERVER_HOST}:${port}/api/wiki/internal/snapshot`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    // Network / server down — drop silently. The wiki page write
+    // itself already succeeded; missing one snapshot is recoverable
+    // (the next save will record the next state).
+  }
+}
+
+main().catch(() => {
+  // Hooks run synchronously to the LLM tool flow — never throw.
+  // A busted hook would make `Write` itself look like it failed
+  // to the LLM, which is much worse than a missing snapshot.
+});

package/server/workspace/wiki-history/provision.ts

@@ -0,0 +1,181 @@
+// Workspace provisioning for the LLM wiki-write hook (#763 PR 2 prereq).
+//
+// At server startup, ensure the workspace's `.claude/settings.json`
+// has a `PostToolUse` hook on Write|Edit that runs our snapshot
+// script. The script itself is rewritten from the source-of-truth
+// constant in `hookScript.ts` on every startup so updates ship via
+// the normal mulmoclaude code path — no per-workspace migration.
+//
+// Idempotent: running provisioning twice produces the same on-disk
+// state. Existing user-supplied keys in `settings.json` are
+// preserved; we only touch the one PostToolUse entry that we own
+// (identified by a `mulmoclaudeWikiHistory: true` marker on the
+// hook descriptor).
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readTextOrNull } from "../../utils/files/safe.js";
+import { writeFileAtomic } from "../../utils/files/atomic.js";
+import { workspacePath as defaultWorkspacePath } from "../workspace.js";
+import { log } from "../../system/logger/index.js";
+
+// The esbuild-built bundle is the source of truth for the hook
+// script written into `<workspace>/.claude/hooks/`. Source TS is
+// `hook/snapshot.ts`; `yarn build:hooks` (chained from
+// `yarn build`) regenerates `hook/snapshot.mjs`, and CI fails
+// when the committed bundle drifts from the source. The read
+// happens inside `provisionWikiHistoryHook` (not at module load)
+// so a missing / unreadable bundle degrades to a logged warning
+// without breaking server startup — provisioning is best-effort
+// and the rest of the server still functions (codex review
+// iter-1 #955).
+const HOOK_BUNDLE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "hook", "snapshot.mjs");
+
+function readHookBundle(): string | null {
+  try {
+    return readFileSync(HOOK_BUNDLE_PATH, "utf-8");
+  } catch (err) {
+    log.warn("wiki-history", "hook bundle unreadable, skipping provisioning", {
+      bundlePath: HOOK_BUNDLE_PATH,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}
+
+const SETTINGS_REL = path.join(".claude", "settings.json");
+const HOOK_SCRIPT_REL = path.join(".claude", "hooks", "wiki-snapshot.mjs");
+// Forward-slash form for the shell command field — settings.json
+// is read by Claude CLI, and a hook command is interpreted by a
+// POSIX shell (Mac / Linux / inside the Docker container). We never
+// embed the workspace root directly: the same settings.json is
+// bind-mounted into the container, so a host-absolute path
+// (`/Users/.../mulmoclaude/...`) silently fails inside the container
+// where the workspace lives at `/home/node/mulmoclaude/...`. Claude
+// CLI exports `CLAUDE_PROJECT_DIR` to hooks, which resolves
+// correctly in both contexts.
+const HOOK_SCRIPT_REL_POSIX = ".claude/hooks/wiki-snapshot.mjs";
+const HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${HOOK_SCRIPT_REL_POSIX}"`;
+const OWNER_MARKER = "mulmoclaudeWikiHistory";
+
+interface HookCommandEntry {
+  type: "command";
+  command: string;
+  [key: string]: unknown;
+}
+
+interface HookMatcher {
+  matcher?: string;
+  hooks?: HookCommandEntry[];
+  [key: string]: unknown;
+}
+
+interface SettingsShape {
+  hooks?: {
+    PostToolUse?: HookMatcher[];
+    [key: string]: HookMatcher[] | undefined;
+  };
+  [key: string]: unknown;
+}
+
+export interface ProvisionOptions {
+  workspaceRoot?: string;
+}
+
+/** Ensure the hook script + `.claude/settings.json` are up to date.
+ *  Safe to call on every startup. Logs a one-line info on first
+ *  install, debug-only on subsequent no-op runs. Skips quietly
+ *  (with a warning) when the bundled hook script can't be read
+ *  — provisioning is best-effort and the rest of the server is
+ *  still functional. */
+export async function provisionWikiHistoryHook(opts: ProvisionOptions = {}): Promise<void> {
+  const bundle = readHookBundle();
+  if (bundle === null) return;
+
+  const root = opts.workspaceRoot ?? defaultWorkspacePath;
+  const scriptPath = path.join(root, HOOK_SCRIPT_REL);
+  const settingsPath = path.join(root, SETTINGS_REL);
+
+  await writeHookScript(scriptPath, bundle);
+  const changed = await mergeHookIntoSettings(settingsPath);
+  if (changed) {
+    log.info("wiki-history", "provisioned wiki-snapshot hook", { settingsPath, scriptPath });
+  }
+}
+
+async function writeHookScript(absPath: string, bundle: string): Promise<void> {
+  // Always overwrite — the esbuild bundle on disk is the source of
+  // truth, and rewriting on every startup means a mulmoclaude
+  // update propagates without per-workspace migration.
+  await writeFileAtomic(absPath, bundle, { mode: 0o700 });
+}
+
+async function mergeHookIntoSettings(settingsPath: string): Promise<boolean> {
+  const existingRaw = await readTextOrNull(settingsPath);
+  const existing: SettingsShape = existingRaw ? safeParse(existingRaw) : {};
+
+  const desiredHook: HookCommandEntry = {
+    type: "command",
+    command: HOOK_COMMAND,
+    [OWNER_MARKER]: true,
+  };
+
+  const next = upsertOurHook(existing, desiredHook);
+  const nextRaw = `${JSON.stringify(next, null, 2)}\n`;
+  if (existingRaw === nextRaw) return false;
+
+  // mode 0644 is fine — settings.json doesn't carry secrets, and
+  // matching the user's own conventions for `~/.claude/settings.json`
+  // (which is typically world-readable) avoids permission surprises.
+  await writeFileAtomic(settingsPath, nextRaw);
+  return true;
+}
+
+function safeParse(raw: string): SettingsShape {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as SettingsShape;
+    }
+  } catch {
+    // Fall through — corrupted settings get rebuilt with our entry only.
+  }
+  return {};
+}
+
+function upsertOurHook(settings: SettingsShape, desiredHook: HookCommandEntry): SettingsShape {
+  const hooks = settings.hooks ?? {};
+  // Normalise to [] when an unexpected shape sits under `PostToolUse`
+  // (object, string, etc.). The `?? []` form only handles
+  // null/undefined; without this guard, `findIndex` throws and the
+  // hook silently fails to install for the session (codex iter-2 #917).
+  const rawPostToolUse = hooks.PostToolUse;
+  const postToolUse = Array.isArray(rawPostToolUse) ? rawPostToolUse : [];
+
+  const ownedIndex = postToolUse.findIndex((entry) => entryHasOwnedHook(entry));
+  const desiredEntry: HookMatcher = {
+    matcher: "Write|Edit",
+    hooks: [desiredHook],
+  };
+
+  const nextPostToolUse = [...postToolUse];
+  if (ownedIndex === -1) {
+    nextPostToolUse.push(desiredEntry);
+  } else {
+    nextPostToolUse[ownedIndex] = desiredEntry;
+  }
+
+  return {
+    ...settings,
+    hooks: {
+      ...hooks,
+      PostToolUse: nextPostToolUse,
+    },
+  };
+}
+
+function entryHasOwnedHook(entry: HookMatcher): boolean {
+  if (!Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some((hook) => hook[OWNER_MARKER] === true);
+}