hippocamp 0.2.2 → 0.2.4

package/scripts/hippocamp-memory.cjs

@@ -28,6 +28,11 @@ const SEARCH_FIELD_BOOST = { cues: 3, heading: 2 };
 const SEARCH_FUZZY_DISTANCE = 0.2;
 const SEARCH_INDEX_CACHE_LIMIT = 8;
 const SEARCH_EXCERPT_MAX_CHARS = 1200;
+// Below this share of a question's rare-word weight, the best match is about something else.
+const SEARCH_MIN_RARE_WORD_COVERAGE = 0.3;
+const QUESTION_STOPWORDS = new Set(
+  "the and for with does did our are was were what which when where why how who can this that from have has had should would could there their them they you your use used about into after before over then than any all".split(" "),
+);
 const EVENT_LOCK_RETRY_MS = 10;
 const EVENT_LOCK_STALE_MS = 10_000;
 const searchIndexCache = new Map();
@@ -434,6 +439,17 @@ async function getGitRepoRoot(startPath) {
   return result.stdout;
 }
 
+// Resolve symlinks in a path whose last parts may not exist yet, so it compares with
+// Git's top level, which Git always reports resolved (macOS /tmp is /private/tmp).
+function realpathExisting(targetPath) {
+  try {
+    return fsSync.realpathSync(targetPath);
+  } catch {
+    const parent = path.dirname(targetPath);
+    return parent === targetPath ? targetPath : path.join(realpathExisting(parent), path.basename(targetPath));
+  }
+}
+
 async function syncMemory({ scope, projectRoot, paths, message }) {
   const repoCandidate = getGlobalRepoRoot();
   const repoRoot = await getGitRepoRoot(repoCandidate);
@@ -450,7 +466,14 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
 
   const repoRelativePaths = paths.map((item) => {
     const relativePath =
-      path.relative(repoRoot, assertPathInScope(scopeRoot, item)).split(path.sep).join(path.posix.sep) || ".";
+      path
+        .relative(
+          realpathExisting(repoRoot),
+          // Recheck after resolving: a symlink inside the Lagoon must not reach another scope.
+          assertPathInScope(realpathExisting(scopeRoot), realpathExisting(assertPathInScope(scopeRoot, item))),
+        )
+        .split(path.sep)
+        .join(path.posix.sep) || ".";
 
     if (relativePath === ".") {
       throw new Error("path must point to a memory file or directory inside the Lagoon root.");
@@ -747,6 +770,7 @@ function createQueryInfo(query) {
     normalized: tokens.join(" "),
     cue: tokens.join("-"),
     tokens,
+    datePrefixes: queryDatePrefixes(original),
   };
 }
 
@@ -895,7 +919,7 @@ function splitOversizedBlock(block) {
   return chunks;
 }
 
-function createSearchExcerpt(content, queryInfo) {
+function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
   const trimmed = content.trim();
 
   if (!trimmed) {
@@ -930,14 +954,17 @@ function createSearchExcerpt(content, queryInfo) {
   let length = 0;
 
   // Keep the best-matching paragraphs that fit the excerpt budget, in file order.
-  for (const hit of index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE })) {
-    const added = blocks[hit.id].length + (picked.length ? 2 : 0);
+  const hits = index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE }).map((hit) => hit.id);
+
+  // An event chosen by its date may share no words with the query; then lead with its first paragraphs.
+  for (const id of hits.length || !leadWhenUnmatched ? hits : blocks.map((_, position) => position)) {
+    const added = blocks[id].length + (picked.length ? 2 : 0);
 
     if (length + added > SEARCH_EXCERPT_MAX_CHARS) {
       continue;
     }
 
-    picked.push(hit.id);
+    picked.push(id);
     length += added;
   }
 
@@ -1214,9 +1241,47 @@ async function collectMarkdownDocuments({ scope, root, curatedFiles }) {
   };
 }
 
+const MONTH_NAMES = "january february march april may june july august september october november december".split(" ");
+
+// Search word for a UTC day ("2026-08-05" -> "d20260805") or month ("2026-08" -> "august").
+// A day is one exact word, so it never matches a neighbor day by typo tolerance.
+function dateTerm(prefix) {
+  return prefix.length === 10 ? `d${prefix.replace(/-/g, "")}` : MONTH_NAMES[Number(prefix.slice(5, 7)) - 1];
+}
+
+// Month and day words of an event's timestamp id.
+function eventDateText(id) {
+  return /^\d{4}-\d{2}-\d{2}T/.test(id || "") ? `${dateTerm(id.slice(0, 7))} ${dateTerm(id.slice(0, 10))}` : "";
+}
+
+// Dates a query asks for: YYYY-MM-DD dates and relative phrases, as UTC day
+// ("2026-08-05") or month ("2026-08") prefixes of event ids. Weeks start on Monday.
+function queryDatePrefixes(query, now = new Date()) {
+  const text = query.toLowerCase();
+  const prefixes = [...text.matchAll(/\b\d{4}-\d{2}-\d{2}\b/g)].map((match) => match[0]);
+  const utc = (months, days) =>
+    new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + months, days)).toISOString();
+  const addDays = (from, to) => {
+    for (let offset = from; offset <= to; offset += 1) {
+      prefixes.push(utc(0, now.getUTCDate() + offset).slice(0, 10));
+    }
+  };
+  const addMonth = (offset) => prefixes.push(utc(offset, 1).slice(0, 7));
+  const monday = -((now.getUTCDay() + 6) % 7);
+
+  if (/\btoday\b/.test(text)) addDays(0, 0);
+  if (/\byesterday\b/.test(text)) addDays(-1, -1);
+  if (/\bthis week\b/.test(text)) addDays(monday, 0);
+  if (/\blast week\b/.test(text)) addDays(monday - 7, monday - 1);
+  if (/\bthis month\b/.test(text)) addMonth(0);
+  if (/\blast month\b/.test(text)) addMonth(-1);
+
+  return prefixes;
+}
+
 function buildSearchIndex(documents) {
   const index = new MiniSearch({
-    fields: ["cues", "heading", "body"],
+    fields: ["cues", "heading", "body", "date"],
     idField: "position",
     tokenize: tokenizeSearchText,
     processTerm: (term) => term,
@@ -1228,6 +1293,7 @@ function buildSearchIndex(documents) {
       cues: (document.cues || []).join(" "),
       heading: document.heading || document.path,
       body: document.body,
+      date: eventDateText(document.id),
     })),
   );
 
@@ -1235,20 +1301,49 @@ function buildSearchIndex(documents) {
 }
 
 function rankSearchDocuments(queryInfo, { index, documents }) {
+  const { datePrefixes } = queryInfo;
+
+  // A date the query asks for filters events to those dates. Undated files always pass.
   return index
-    .search(queryInfo.normalized, {
+    .search([queryInfo.normalized, ...datePrefixes.map(dateTerm)].join(" "), {
       boost: SEARCH_FIELD_BOOST,
-      fuzzy: SEARCH_FUZZY_DISTANCE,
+      fuzzy: (term) => (/^d\d{8}$/.test(term) ? 0 : SEARCH_FUZZY_DISTANCE),
+      filter: datePrefixes.length
+        ? (hit) => !documents[hit.id].id || datePrefixes.some((prefix) => documents[hit.id].id.startsWith(prefix))
+        : undefined,
     })
     .slice(0, SEARCH_CANDIDATE_LIMIT)
     .map((hit) => ({
       document: documents[hit.id],
       score: Math.round(hit.score * 100) / 100,
+      queryTerms: hit.queryTerms,
     }));
 }
 
+// Share of the question's rare-word weight (IDF) that the best match contains. A question
+// whose rare words ("kubernetes", "namespace") appear in no memory gets a low share even when
+// common words ("backend", "deploy") match, so search can return nothing instead of noise.
+function rareWordCoverage(queryInfo, best, { index, documents }) {
+  // Month names only rank (see eventDateText); they say when, not what.
+  const words = [
+    ...new Set(
+      queryInfo.tokens.filter((token) => token.length > 2 && !QUESTION_STOPWORDS.has(token) && !MONTH_NAMES.includes(token)),
+    ),
+  ];
+
+  if (!words.length) {
+    return 1;
+  }
+
+  const weight = (word) => Math.log(1 + documents.length / (index.search(word, { fuzzy: 0 }).length + 0.5));
+  const matched = new Set(best?.queryTerms || []);
+  const total = words.reduce((sum, word) => sum + weight(word), 0);
+
+  return words.filter((word) => matched.has(word)).reduce((sum, word) => sum + weight(word), 0) / total;
+}
+
 function toSearchResult(queryInfo, { document, score }) {
-  const snippet = createSearchExcerpt(document.body, queryInfo);
+  const snippet = createSearchExcerpt(document.body, queryInfo, queryInfo.datePrefixes.length > 0);
 
   if (!snippet) {
     return null;
@@ -1343,8 +1438,14 @@ async function searchMemory({ query, scope = "both", projectRoot, maxResults = 5
   const search = await loadSearchIndex(scopes, projectRoot);
   const results = [];
 
-  if (queryInfo.tokens.length && search.documents.length) {
-    for (const candidate of rankSearchDocuments(queryInfo, search)) {
+  const candidates = queryInfo.tokens.length && search.documents.length ? rankSearchDocuments(queryInfo, search) : [];
+  // Dated questions skip the check: their date words describe time, not the topic.
+  const related =
+    queryInfo.datePrefixes.length > 0 ||
+    rareWordCoverage(queryInfo, candidates[0], search) >= SEARCH_MIN_RARE_WORD_COVERAGE;
+
+  if (related) {
+    for (const candidate of candidates) {
       const result = toSearchResult(queryInfo, candidate);
 
       if (result) {

package/scripts/hippocamp.cjs

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 
-const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const { spawn, spawnSync } = require("node:child_process");
 const path = require("node:path");
 
+// One installer per agent CLI; `install` runs the ones whose CLI is on PATH.
+const AGENTS = [
+  ["claude", "install-claude.cjs"],
+  ["codex", "install-codex.cjs"],
+  ["grok", "install-grok.cjs"],
+];
+
 const COMMANDS = {
   dream: "hippocamp-dream.cjs",
   mcp: "hippocamp-mcp.cjs",
@@ -18,6 +26,8 @@ function printHelp() {
   console.log(`Hippocamp
 
 Usage:
+  hippocamp install
+  hippocamp upgrade
   hippocamp dream
   hippocamp mcp
   hippocamp install-codex
@@ -28,6 +38,8 @@ Usage:
   hippocamp upgrade-grok
 
 Commands:
+  install         Install into every agent found: Claude Code, Codex, Grok Build
+  upgrade         Same as install; run with npx hippocamp@latest
   dream           Run offline Dream memory compaction
   mcp             Run the local MCP server
   install-codex   Install the Hippocamp skill and MCP server into Codex
@@ -39,6 +51,35 @@ Commands:
 `);
 }
 
+// Platform-neutral PATH lookup, so `install` also finds agents on Windows.
+function onPath(cli) {
+  const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".EXE;.CMD").split(";") : [""];
+
+  return String(process.env.PATH || "")
+    .split(path.delimiter)
+    .some((dir) => extensions.some((extension) => fs.existsSync(path.join(dir, cli + extension.toLowerCase())) || fs.existsSync(path.join(dir, cli + extension))));
+}
+
+function installAll(args) {
+  const found = AGENTS.filter(([cli]) => onPath(cli));
+
+  if (!found.length) {
+    console.error("No supported agent CLI found on PATH: claude, codex, or grok. Install one, then rerun.");
+    process.exit(1);
+  }
+
+  // Install every agent found, even when one fails, then report the failures.
+  const failed = found.filter(([cli, script]) => {
+    console.error(`Installing Hippocamp into ${cli}...`);
+    return spawnSync(process.execPath, [path.join(__dirname, script), ...args], { stdio: "inherit" }).status !== 0;
+  });
+
+  if (failed.length) {
+    console.error(`Install failed for: ${failed.map(([cli]) => cli).join(", ")}`);
+    process.exit(1);
+  }
+}
+
 function main() {
   const [command, ...args] = process.argv.slice(2);
 
@@ -47,6 +88,11 @@ function main() {
     return;
   }
 
+  if (command === "install" || command === "upgrade") {
+    installAll(args);
+    return;
+  }
+
   const script = COMMANDS[command];
 
   if (!script) {

package/scripts/install-claude.cjs

@@ -5,6 +5,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { execFile } = require("node:child_process");
 const { promisify } = require("node:util");
+const { mcpServerCommand, prepareLagoon, printHints } = require("./install-common.cjs");
 
 const execFileAsync = promisify(execFile);
 
@@ -204,7 +205,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     }
   }
 
-  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const command = mcpServerCommand(repoRoot);
   const added = await runClaude([
     "mcp",
     "add",
@@ -218,8 +219,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     "--env",
     "HIPPOCAMP_AGENT=claude",
     "--",
-    process.execPath,
-    scriptPath,
+    ...command,
   ]);
 
   if (!added.ok) {
@@ -228,8 +228,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
 
   return {
     name: serverName,
-    command: process.execPath,
-    scriptPath,
+    command: command.join(" "),
     globalRoot,
     summary: added.stdout || added.stderr,
   };
@@ -249,6 +248,7 @@ async function main() {
     repoRoot,
   });
 
+  const lagoon = await prepareLagoon(options.globalRoot);
   const server = await ensureServerInstalled({
     repoRoot,
     globalRoot: options.globalRoot,
@@ -263,12 +263,14 @@ async function main() {
         claudeMdPath,
         claudeSkillPath,
         server,
+        lagoon,
         note: "Restart Claude Code to load the installed MCP server, Hippocamp skill, and refreshed CLAUDE.md instructions.",
       },
       null,
       2,
     ),
   );
+  printHints(lagoon);
 }
 
 main().catch((error) => {

package/scripts/install-codex.cjs

@@ -5,6 +5,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { execFile } = require("node:child_process");
 const { promisify } = require("node:util");
+const { mcpServerCommand, prepareLagoon, printHints } = require("./install-common.cjs");
 
 const execFileAsync = promisify(execFile);
 const CODEX_MANAGED_START = "<!-- hippocamp:managed:start -->";
@@ -174,7 +175,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     }
   }
 
-  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const command = mcpServerCommand(repoRoot);
   const added = await runCodex([
     "mcp",
     "add",
@@ -184,8 +185,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     "--env",
     "HIPPOCAMP_AGENT=codex",
     "--",
-    process.execPath,
-    scriptPath,
+    ...command,
   ]);
 
   if (!added.ok) {
@@ -194,8 +194,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
 
   return {
     name: serverName,
-    command: process.execPath,
-    scriptPath,
+    command: command.join(" "),
     globalRoot,
     summary: added.stdout || added.stderr,
   };
@@ -215,6 +214,7 @@ async function main() {
     codexHome: options.codexHome,
   });
 
+  const lagoon = await prepareLagoon(options.globalRoot);
   const server = await ensureServerInstalled({
     repoRoot,
     globalRoot: options.globalRoot,
@@ -229,12 +229,14 @@ async function main() {
         skillPath,
         codexInstructionsPath,
         server,
+        lagoon,
         note: "Restart Codex to load the installed skill, MCP server, and refreshed AGENTS.md instructions.",
       },
       null,
       2,
     ),
   );
+  printHints(lagoon);
 }
 
 main().catch((error) => {

package/scripts/install-common.cjs

@@ -0,0 +1,91 @@
+const fsSync = require("node:fs");
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { execFile } = require("node:child_process");
+const { promisify } = require("node:util");
+
+const execFileAsync = promisify(execFile);
+
+// How an agent starts the MCP server. Run through npx, the package lives in npm's cache,
+// which npm may clean; a pinned npx command downloads it again instead of breaking.
+function mcpServerCommand(repoRoot) {
+  if (!repoRoot.split(path.sep).includes("_npx")) {
+    return [process.execPath, path.join(repoRoot, "scripts", "hippocamp-mcp.cjs")];
+  }
+
+  const { version } = require(path.join(repoRoot, "package.json"));
+  const npx = path.join(path.dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx");
+
+  return [fsSync.existsSync(npx) ? npx : path.basename(npx), "-y", "--prefer-offline", `hippocamp@${version}`, "mcp"];
+}
+
+async function git(args, cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd,
+      timeout: 20_000,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return { ok: true, stdout: stdout.trim() };
+  } catch (error) {
+    return { ok: false, stdout: String(error.stdout || "").trim() };
+  }
+}
+
+// Make sure the Lagoon memory repo exists, and say what is still missing for sync.
+// It never creates a remote or pushes: those reach outside this machine.
+async function prepareLagoon(globalRoot) {
+  const hints = [];
+  let created = false;
+  const existed = fsSync.existsSync(globalRoot);
+  const empty = !existed || (await fs.readdir(globalRoot)).length === 0;
+
+  await fs.mkdir(globalRoot, { recursive: true });
+
+  // The Lagoon must be its own repo: a folder inside another repo would commit memory there.
+  const topLevel = await git(["rev-parse", "--show-toplevel"], globalRoot);
+  const ownRepo = topLevel.ok && fsSync.realpathSync(topLevel.stdout) === fsSync.realpathSync(globalRoot);
+
+  if (!ownRepo) {
+    if (!empty) {
+      hints.push(`${globalRoot} is not its own Git repo. Point --global-root at your Lagoon clone, or run: git -C "${globalRoot}" init`);
+      return { root: globalRoot, created: false, remote: null, push: "not_git", hints };
+    }
+
+    if (!(await git(["init", "-b", "main"], globalRoot)).ok) {
+      throw new Error(`git init failed in ${globalRoot}. Check that Git is installed and the folder is writable.`);
+    }
+
+    await git(["commit", "--allow-empty", "-m", "hippocamp: create lagoon"], globalRoot);
+    created = true;
+  }
+
+  const identity = await Promise.all(["user.name", "user.email"].map((key) => git(["config", key], globalRoot)));
+
+  if (identity.some((value) => !value.stdout)) {
+    hints.push('Set a Git identity so memory can be committed: git config --global user.name "Your Name" && git config --global user.email you@example.com');
+  }
+
+  const remote = await git(["remote", "get-url", "origin"], globalRoot);
+  let push = "no_remote";
+
+  if (!remote.ok) {
+    hints.push(`Memory is local only. For a private backup and other machines: gh repo create lagoon --private --source "${globalRoot}" --remote origin --push`);
+  } else if ((await git(["rev-parse", "--verify", "HEAD"], globalRoot)).ok) {
+    push = (await git(["push", "--dry-run"], globalRoot)).ok ? "ok" : "failed";
+
+    if (push === "failed") {
+      hints.push(`Git push from ${globalRoot} failed. Set up auth, then check with git push --dry-run: gh auth login && gh auth setup-git`);
+    }
+  }
+
+  return { root: globalRoot, created, remote: remote.ok ? remote.stdout : null, push, hints };
+}
+
+function printHints(lagoon) {
+  for (const hint of lagoon.hints) {
+    console.error(`Next: ${hint}`);
+  }
+}
+
+module.exports = { mcpServerCommand, prepareLagoon, printHints };

package/scripts/install-grok.cjs

@@ -5,6 +5,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { execFile } = require("node:child_process");
 const { promisify } = require("node:util");
+const { mcpServerCommand, prepareLagoon, printHints } = require("./install-common.cjs");
 
 const execFileAsync = promisify(execFile);
 const GROK_MANAGED_START = "<!-- hippocamp:managed:start -->";
@@ -190,7 +191,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     }
   }
 
-  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const command = mcpServerCommand(repoRoot);
   const added = await runGrok([
     "mcp",
     "add",
@@ -200,8 +201,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     "-e",
     "HIPPOCAMP_AGENT=grok",
     "--",
-    process.execPath,
-    scriptPath,
+    ...command,
   ]);
 
   if (!added.ok) {
@@ -210,8 +210,7 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
 
   return {
     name: serverName,
-    command: process.execPath,
-    scriptPath,
+    command: command.join(" "),
     globalRoot,
     agent: "grok",
     summary: added.stdout || added.stderr,
@@ -232,6 +231,7 @@ async function main() {
     grokHome: options.grokHome,
   });
 
+  const lagoon = await prepareLagoon(options.globalRoot);
   const server = await ensureServerInstalled({
     repoRoot,
     globalRoot: options.globalRoot,
@@ -246,12 +246,14 @@ async function main() {
         skillPath,
         grokInstructionsPath,
         server,
+        lagoon,
         note: "Restart Grok Build (or start a new session) to load the installed skill, MCP server, and home rules.",
       },
       null,
       2,
     ),
   );
+  printHints(lagoon);
 }
 
 main().catch((error) => {

package/skills/hippocamp-memory/SKILL.md

@@ -25,6 +25,7 @@ Upgrade uses the same path: run `npm run upgrade:codex`, `npm run upgrade:claude
 1. At the start of every top-level coding task, call `wake_up` before inspecting files, planning, or editing.
 2. Read the wake-up output before searching.
 3. Use `search_memory` as the normal path for task-specific recall after wake-up.
+   Keep the default 5 results for a single fact. Pass `maxResults` 10-20 when the question combines several past sessions (counts, totals, comparisons, timelines), and search again if the results look incomplete.
 4. If search returns no result, continue without memory. Do not read whole event logs as a fallback.
 5. During work, use `append_event` only for meaningful milestones.
 6. When appending events, pass a `title` and 1-8 concise `cues` so fuzzy recall can find the event later. Never write under `events/` with `write_memory_file`.

package/test/install-common.test.cjs

@@ -0,0 +1,112 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { execFileSync } = require("node:child_process");
+const fsSync = require("node:fs");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { mcpServerCommand, prepareLagoon } = require("../scripts/install-common.cjs");
+
+// CI runners have no Git identity; commits in these tests need one.
+const gitEnv = {
+  GIT_AUTHOR_NAME: "Test",
+  GIT_AUTHOR_EMAIL: "test@example.com",
+  GIT_COMMITTER_NAME: "Test",
+  GIT_COMMITTER_EMAIL: "test@example.com",
+};
+
+// Scoped to each test that needs a Git identity, then restored.
+function useGitIdentity(t) {
+  const saved = Object.fromEntries(Object.keys(gitEnv).map((key) => [key, process.env[key]]));
+  Object.assign(process.env, gitEnv);
+  t.after(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+async function tempDir(t, name) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), `hippocamp-${name}-`));
+  t.after(() => fs.rm(root, { recursive: true, force: true, maxRetries: 5 }));
+  return root;
+}
+
+test("mcpServerCommand pins npx installs and keeps source checkouts direct", async (t) => {
+  const root = await tempDir(t, "npx");
+  const npxRoot = path.join(root, "_npx", "abc", "node_modules", "hippocamp");
+  await fs.mkdir(npxRoot, { recursive: true });
+  await fs.writeFile(path.join(npxRoot, "package.json"), '{ "version": "9.9.9" }');
+
+  assert.deepEqual(mcpServerCommand(npxRoot).slice(1), ["-y", "--prefer-offline", "hippocamp@9.9.9", "mcp"]);
+  const source = path.join(root, "src", "hippocamp");
+  assert.deepEqual(mcpServerCommand(source), [process.execPath, path.join(source, "scripts", "hippocamp-mcp.cjs")]);
+});
+
+test("prepareLagoon creates a missing Lagoon repo and says it is local only", async (t) => {
+  useGitIdentity(t);
+  const lagoon = path.join(await tempDir(t, "lagoon"), "lagoon");
+  const result = await prepareLagoon(lagoon);
+
+  assert.equal(result.created, true);
+  assert.equal(result.push, "no_remote");
+  assert.match(result.hints.join("\n"), /gh repo create lagoon --private/);
+  assert.equal(execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: lagoon }).toString().trim(), "true");
+});
+
+test("prepareLagoon leaves a non-empty folder that is not a repo alone", async (t) => {
+  const folder = await tempDir(t, "notes");
+  await fs.writeFile(path.join(folder, "notes.md"), "mine\n");
+  const result = await prepareLagoon(folder);
+
+  assert.equal(result.push, "not_git");
+  await assert.rejects(fs.stat(path.join(folder, ".git")));
+});
+
+test("prepareLagoon checks push to an existing remote", async (t) => {
+  useGitIdentity(t);
+  const root = await tempDir(t, "remote");
+  const remote = path.join(root, "remote.git");
+  const lagoon = path.join(root, "lagoon");
+  execFileSync("git", ["init", "--bare", "-b", "main", remote]);
+  execFileSync("git", ["init", "-b", "main", lagoon]);
+  execFileSync("git", ["commit", "--allow-empty", "-m", "init"], { cwd: lagoon });
+  execFileSync("git", ["remote", "add", "origin", remote], { cwd: lagoon });
+  execFileSync("git", ["push", "-u", "origin", "main"], { cwd: lagoon, stdio: "ignore" });
+
+  const result = await prepareLagoon(lagoon);
+
+  assert.equal(result.created, false);
+  assert.equal(result.remote, remote);
+  assert.equal(result.push, "ok");
+});
+
+test("prepareLagoon refuses a folder inside another repo", async (t) => {
+  useGitIdentity(t);
+  const parent = await tempDir(t, "parent");
+  execFileSync("git", ["init", "-b", "main", parent]);
+  const nested = path.join(parent, "notes");
+  await fs.mkdir(nested);
+  await fs.writeFile(path.join(nested, "a.md"), "x\n");
+
+  const result = await prepareLagoon(nested);
+
+  assert.equal(result.push, "not_git");
+  await assert.rejects(fs.stat(path.join(nested, ".git")));
+});
+
+test("prepareLagoon gives an empty folder inside another repo its own repo", async (t) => {
+  useGitIdentity(t);
+  const parent = await tempDir(t, "parent-empty");
+  execFileSync("git", ["init", "-b", "main", parent]);
+  const nested = path.join(parent, "lagoon");
+
+  const result = await prepareLagoon(nested);
+
+  assert.equal(result.created, true);
+  assert.equal(fsSync.realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: nested }).toString().trim()), fsSync.realpathSync(nested));
+});