@mercury-fw/core 0.25.0

package/src/wiki/wiki-note.ts

@@ -0,0 +1,326 @@
+/**
+ * Typed writers for wiki notes — the "template" that takes
+ * structured fields instead of a free-form file write: each function
+ * validates its fields against the frontmatter schema
+ * (frontmatter-schema.ts), serializes YAML frontmatter + markdown body,
+ * and writes the result under the vault path (vault-init.ts creates the
+ * surrounding curated/inferred directories).
+ *
+ * These are plain functions, not model-invocable tools — mirrors the
+ * split already used for CLIs (cli-executor.ts/command-parser.ts do the
+ * work, cli-tool.ts wraps a subset in `tool()` for the model). Whether
+ * either of these gets a `tool()` wrapper is a separate, later decision:
+ * `writeInferredNote` in particular must stay internal-only, called
+ * exclusively by the deterministic consolidation engine — never
+ * exposed to the model, since that would reopen the question of letting
+ * the LLM decide when to write semantic memory, deliberately kept
+ * mechanical/deterministic instead.
+ *
+ * Path segments coming from outside Mercury's own code (userId, topic)
+ * are resolved and checked against the vault root before any write — a
+ * topic string is LLM-produced free text, nothing upstream guarantees
+ * it can't contain `..` or `/`.
+ */
+import { mkdir, writeFile, stat } from "node:fs/promises";
+import { resolve, sep, dirname, relative } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import {
+  CuratedFrontmatterSchema,
+  InferredFrontmatterSchema,
+  ConfirmationFrontmatterSchema,
+  type CuratedFrontmatter,
+  type InferredFrontmatter,
+  type ConfirmationFrontmatter,
+} from "./frontmatter-schema.ts";
+
+/**
+ * Resolves `segments` against `root` and checks the result stays inside
+ * `root` — not just inside the vault as a whole. `root` must already be
+ * the *specific* subtree a given write is scoped to (`curated/`, or one
+ * user's `inferred/users/<userId>/`): checking only against the vault
+ * root would let a relativePath like `"../inferred/users/x/y.md"` escape
+ * `curated/` while still landing somewhere else inside the vault.
+ */
+function resolveWithinRoot(root: string, ...segments: string[]): string {
+  const resolvedRoot = resolve(root);
+  const target = resolve(resolvedRoot, ...segments);
+  if (target !== resolvedRoot && !target.startsWith(resolvedRoot + sep)) {
+    throw new Error(`refusing to write outside ${root}: ${segments.join("/")}`);
+  }
+  return target;
+}
+
+function assertNoPathSeparator(label: string, value: string): void {
+  if (value === "" || value.includes("/") || value.includes("\\") || value === "." || value === "..") {
+    throw new Error(`invalid ${label}: ${JSON.stringify(value)}`);
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Mercury's own git identity, passed inline on every commit (`-c
+// user.email=...`) rather than relying on global/system git config —
+// self-contained, works the same in a fresh dev checkout, in tests, and in
+// any deployment, with nothing to set up out-of-band. Distinct from any
+// human's own git identity, so `git log --author`/`git blame` cleanly
+// separate Mercury's automated writes from a maintainer's — the actual
+// provenance mechanism the vault's audit trail already relies on, not
+// a schema-level flag.
+const MERCURY_GIT_AUTHOR = { email: "mercury@comperio.local", name: "Mercury" };
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    // git prints some failure reasons (e.g. "nothing to commit") to
+    // stdout, not stderr — found by hand via the maintenance CLI, where a
+    // stderr-only message came back empty and gave no clue what failed.
+    throw new Error(`git ${args.join(" ")} failed in ${cwd}: ${stderr || stdout}`);
+  }
+}
+
+/** True if `git add` staged at least one real change — i.e. there's
+ * something for `git commit` to actually record. */
+async function hasStagedChanges(cwd: string): Promise<boolean> {
+  const proc = Bun.spawn(["git", "diff", "--cached", "--quiet"], { cwd });
+  const exitCode = await proc.exited;
+  return exitCode !== 0; // --quiet: 0 = no differences, 1 = differences
+}
+
+// git add/commit against the same repo aren't safe to run concurrently
+// (index lock races) — every writer below shares one vault/repo, so this
+// chain is shared across all of them, not per-function. `.then(fn, fn)`
+// runs the next write regardless of whether the previous one succeeded or
+// failed, so one bad commit doesn't wedge every write after it; the
+// rejection itself still propagates to that specific caller via `result`.
+// If the file write already landed on disk before a later git step throws
+// (disk full, corrupt repo), `writeNoteFile` logs a dedicated
+// `[wiki-vault] ... written to disk but not committed` line before
+// rethrowing — distinguishable from a generic failure by whatever reads
+// stderr (`docker compose logs` today; the admin-notification path this
+// could eventually route through isn't wired up for this specific
+// signal yet).
+let commitChain: Promise<void> = Promise.resolve();
+
+function serializeCommit<T>(fn: () => Promise<T>): Promise<T> {
+  const result = commitChain.then(fn, fn);
+  commitChain = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  return result;
+}
+
+/**
+ * Every vault write is a commit — audit trail + `git revert` as a
+ * safety net. The file write itself goes through the same queue as the
+ * commit (not just git add/commit) — two writers targeting the same path
+ * must never race directly on disk content; queuing only the git half
+ * left that race open (found and fixed later). This makes "two
+ * writers, one path" deterministic (whichever is processed second wins,
+ * cleanly) rather than a data-loss race with confusing spurious errors —
+ * it does not attempt any merge of old vs new content, by design: nothing
+ * here promises the vault is edited "live" merge-safely, only that each
+ * write, once it runs, is a clean, whole-file, versioned commit.
+ */
+async function writeVerbatimFile(
+  vaultPath: string,
+  fullPath: string,
+  content: string,
+  commitMessage: string,
+): Promise<void> {
+  await serializeCommit(async () => {
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf-8");
+    const relPath = relative(vaultPath, fullPath);
+    try {
+      await runGit(vaultPath, ["add", relPath]);
+      // Byte-identical content to what's already committed stages no diff —
+      // asking the vault to contain X when it already contains exactly X is
+      // a no-op, not a failure, so skip the commit instead of letting `git
+      // commit` fail with "nothing to commit".
+      if (!(await hasStagedChanges(vaultPath))) {
+        return;
+      }
+      await runGit(vaultPath, [
+        "-c",
+        `user.email=${MERCURY_GIT_AUTHOR.email}`,
+        "-c",
+        `user.name=${MERCURY_GIT_AUTHOR.name}`,
+        "commit",
+        "-m",
+        commitMessage,
+      ]);
+    } catch (err) {
+      console.error(`[wiki-vault] ${relPath} written to disk but not committed: ${String(err)}`);
+      throw err;
+    }
+  });
+}
+
+async function writeNoteFile(
+  vaultPath: string,
+  fullPath: string,
+  frontmatter: CuratedFrontmatter | InferredFrontmatter | ConfirmationFrontmatter,
+  body: string,
+  commitMessage: string,
+): Promise<void> {
+  const content = `---\n${stringifyYaml(frontmatter)}---\n\n${body}\n`;
+  await writeVerbatimFile(vaultPath, fullPath, content, commitMessage);
+}
+
+/** `git rm` + commit through the same queue as every writer above, so
+ * the same `git revert` safety net covers deletions too. A target already gone
+ * is a no-op success, not an error — same philosophy as the byte-identical
+ * write no-op above. */
+async function deleteVaultFile(vaultPath: string, fullPath: string, commitMessage: string): Promise<void> {
+  await serializeCommit(async () => {
+    if (!(await pathExists(fullPath))) return;
+    const relPath = relative(vaultPath, fullPath);
+    await runGit(vaultPath, ["rm", "--quiet", relPath]);
+    await runGit(vaultPath, [
+      "-c",
+      `user.email=${MERCURY_GIT_AUTHOR.email}`,
+      "-c",
+      `user.name=${MERCURY_GIT_AUTHOR.name}`,
+      "commit",
+      "-m",
+      commitMessage,
+    ]);
+  });
+}
+
+/** Writes a curated doc at `curated/<relativePath>` (e.g. "standards/jira-fields.md"). */
+export async function writeCuratedNote(
+  vaultPath: string,
+  relativePath: string,
+  fields: { author?: string; last_updated?: string },
+  body: string,
+): Promise<void> {
+  const frontmatter = CuratedFrontmatterSchema.parse({ type: "curated", ...fields });
+  const curatedRoot = resolve(vaultPath, "curated");
+  const fullPath = resolveWithinRoot(curatedRoot, relativePath);
+  await writeNoteFile(vaultPath, fullPath, frontmatter, body, `curated: ${relativePath}`);
+}
+
+/** Writes a semantic note at `inferred/users/<userId>/<topic>.md`. */
+export async function writeInferredNote(
+  vaultPath: string,
+  userId: string,
+  topic: string,
+  fields: { confidence: "low" | "medium" | "high"; derived_from: string[]; last_reviewed: string | null },
+  body: string,
+): Promise<void> {
+  assertNoPathSeparator("userId", userId);
+  assertNoPathSeparator("topic", topic);
+  const frontmatter = InferredFrontmatterSchema.parse({ type: "inferred", source: "agent", ...fields });
+  const inferredUserRoot = resolve(vaultPath, "inferred", "users", userId);
+  const fullPath = resolveWithinRoot(inferredUserRoot, `${topic}.md`);
+  await writeNoteFile(vaultPath, fullPath, frontmatter, body, `inferred: ${userId}/${topic}`);
+}
+
+/**
+ * Writes a deterministically-promoted procedural correction at
+ * `curated/standards/<tool>-<topic>.md` — one file per correction, not
+ * merged into a single per-tool doc (that would need safe section-level
+ * merging into whatever a human already wrote by hand there, e.g.
+ * `curated/standards/jira-cli.md`, deliberately out of scope here).
+ * Frontmatter is still `type: inferred, source: agent` (same provenance
+ * shape as `writeInferredNote` — probabilistic, consolidation-derived, not
+ * human-authored) even though the file lives under `curated/`: the path
+ * controls read visibility (every user's wiki tools expose `curated/`,
+ * only their own `inferred/users/<userId>/`), not authorship.
+ */
+export async function writeToolCorrectionNote(
+  vaultPath: string,
+  tool: string,
+  topic: string,
+  fields: { confidence: "low" | "medium" | "high"; derived_from: string[]; last_reviewed: string | null },
+  body: string,
+): Promise<void> {
+  assertNoPathSeparator("tool", tool);
+  assertNoPathSeparator("topic", topic);
+  const frontmatter = InferredFrontmatterSchema.parse({ type: "inferred", source: "agent", ...fields });
+  const standardsRoot = resolve(vaultPath, "curated", "standards");
+  const fullPath = resolveWithinRoot(standardsRoot, `${tool}-${topic}.md`);
+  await writeNoteFile(vaultPath, fullPath, frontmatter, body, `inferred: standards/${tool}-${topic}`);
+}
+
+/**
+ * Writes (or overwrites) the deterministic lifecycle record for one
+ * confirm-required action at `inferred/confirmations/<encoded userId>/<token>.md`
+ * — see `ConfirmationFrontmatterSchema`'s own doc comment for why this
+ * subtree, not `inferred/users/<userId>/`. Called twice per action: once
+ * at staging (`status: "pending"`, `resolvedAt: null`), once at resolution
+ * (`"confirmed"`/`"failed"`, `resolvedAt` set) — the whole-file replace
+ * every writer here already does, not a partial update.
+ */
+export async function writeConfirmationNote(
+  vaultPath: string,
+  userId: string,
+  token: string,
+  fields: { status: "pending" | "confirmed" | "failed"; requestedAt: string; resolvedAt: string | null; command: string },
+): Promise<void> {
+  assertNoPathSeparator("token", token);
+  const frontmatter = ConfirmationFrontmatterSchema.parse({
+    type: "confirmation",
+    status: fields.status,
+    requested_at: fields.requestedAt,
+    resolved_at: fields.resolvedAt,
+    command: fields.command,
+  });
+  const userRoot = resolve(vaultPath, "inferred", "confirmations", encodeURIComponent(userId));
+  const fullPath = resolveWithinRoot(userRoot, `${token}.md`);
+  await writeNoteFile(vaultPath, fullPath, frontmatter, "", `confirmation: ${userId}/${token} (${fields.status})`);
+}
+
+/** Writes a raw/ inbox entry verbatim at `raw/<relativePath>` — no
+ * frontmatter, content is whatever a human pasted as-is (see
+ * `vault-cli.ts`'s `write-raw`). Never called during a normal
+ * conversation; only the self-review job (`self-review-tools.ts`) reads
+ * this back to triage it into `curated/`. */
+export async function writeRawEntry(vaultPath: string, relativePath: string, body: string): Promise<void> {
+  const rawRoot = resolve(vaultPath, "raw");
+  const fullPath = resolveWithinRoot(rawRoot, relativePath);
+  const content = body.endsWith("\n") ? body : `${body}\n`;
+  await writeVerbatimFile(vaultPath, fullPath, content, `raw: ${relativePath}`);
+}
+
+/** Overwrites `index.md` at the vault root with `content` verbatim — no
+ * frontmatter, it's a generated Karpathy-pattern index, not a note.
+ * Whole-file replace: the caller (self-review) computes the full new
+ * text and passes the complete replacement, same as every writer here. */
+export async function writeIndexFile(vaultPath: string, content: string): Promise<void> {
+  const fullPath = resolve(vaultPath, "index.md");
+  const normalized = content.endsWith("\n") ? content : `${content}\n`;
+  await writeVerbatimFile(vaultPath, fullPath, normalized, "index: update");
+}
+
+/** Deletes a raw/ entry once self-review has resolved it (merged,
+ * promoted, or discarded). */
+export async function deleteRawEntry(vaultPath: string, relativePath: string): Promise<void> {
+  const rawRoot = resolve(vaultPath, "raw");
+  const fullPath = resolveWithinRoot(rawRoot, relativePath);
+  await deleteVaultFile(vaultPath, fullPath, `raw: delete ${relativePath}`);
+}
+
+/** Deletes a curated/ doc — used only by the self-review job to retire a
+ * redundant/superseded doc (never during a normal conversation). Callers
+ * should also remove the doc's `index.md` line in the same pass, so a
+ * deletion doesn't leave a dangling index reference. */
+export async function deleteCuratedEntry(vaultPath: string, relativePath: string): Promise<void> {
+  const curatedRoot = resolve(vaultPath, "curated");
+  const fullPath = resolveWithinRoot(curatedRoot, relativePath);
+  await deleteVaultFile(vaultPath, fullPath, `curated: delete ${relativePath}`);
+}

package/src/wiki/wiki-read.ts

@@ -0,0 +1,122 @@
+/**
+ * Read-side access to the wiki vault: listing, reading, and searching.
+ * Every function is scoped to `curated/` (visible to everyone) plus
+ * `inferred/users/<userId>/` for the *calling* userId only — never
+ * another user's semantic notes (the same per-user isolation already
+ * used for Layer 3/Qdrant, applied to Layer 2 too). Plain
+ * functions, not model-invocable tools — wiki-tools.ts wraps a subset of
+ * these in `tool()` for the model, same split as
+ * cli-executor.ts/cli-tool.ts.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function allowedRoots(vaultPath: string, userId: string): string[] {
+  const vaultRoot = resolve(vaultPath);
+  return [resolve(vaultRoot, "curated"), resolve(vaultRoot, "inferred", "users", userId)];
+}
+
+/** curated/ + raw/ only — never inferred/, for the nightly self-review job.
+ * A distinct trust boundary from a per-user conversation's `allowedRoots`
+ * (which trades curated/ for one user's own inferred/ instead of raw/):
+ * inferred/ is meant to hold only deterministic, mechanically-written
+ * notes (never an LLM's own judgment call about what to remember) —
+ * off-limits here for the same reason it's off-limits to regular
+ * conversations, not a special exception for self-review. */
+export function selfReviewRoots(vaultPath: string): string[] {
+  const vaultRoot = resolve(vaultPath);
+  return [resolve(vaultRoot, "curated"), resolve(vaultRoot, "raw")];
+}
+
+/**
+ * Resolves `relativePath` against the vault and checks it falls under
+ * one of `roots` — rejects both vault escape (`..`) and access outside
+ * the caller's declared scope (cross-user inferred/ access, or anything
+ * outside curated/+raw/ for the self-review job).
+ */
+function resolveAllowedWikiPath(vaultPath: string, roots: string[], relativePath: string): string {
+  const vaultRoot = resolve(vaultPath);
+  const target = resolve(vaultRoot, relativePath);
+  const allowed = roots.some((root) => target === root || target.startsWith(root + sep));
+  if (!allowed) {
+    throw new Error(`path not accessible: ${relativePath}`);
+  }
+  return target;
+}
+
+async function listFilesUnder(root: string, vaultRoot: string): Promise<string[]> {
+  if (!(await pathExists(root))) return [];
+  const glob = new Bun.Glob("**/*.md");
+  const results: string[] = [];
+  for await (const rel of glob.scan({ cwd: root })) {
+    results.push(relative(vaultRoot, join(root, rel)));
+  }
+  return results;
+}
+
+/** Lists every `.md` file under `roots`. */
+export async function listWikiFilesInRoots(vaultPath: string, roots: string[]): Promise<string[]> {
+  const vaultRoot = resolve(vaultPath);
+  const lists = await Promise.all(roots.map((root) => listFilesUnder(root, vaultRoot)));
+  return lists.flat().sort();
+}
+
+/** Lists every `.md` file visible to `userId`: all of curated/, plus only their own inferred/users/<userId>/. */
+export async function listWikiFiles(vaultPath: string, userId: string): Promise<string[]> {
+  return listWikiFilesInRoots(vaultPath, allowedRoots(vaultPath, userId));
+}
+
+/** Reads a single wiki file. Throws if `relativePath` falls outside `roots`. */
+export async function readWikiFileInRoots(vaultPath: string, roots: string[], relativePath: string): Promise<string> {
+  const fullPath = resolveAllowedWikiPath(vaultPath, roots, relativePath);
+  return readFile(fullPath, "utf-8");
+}
+
+/** Reads a single wiki file. Throws if `relativePath` falls outside the caller's allowed scope. */
+export async function readWikiFile(vaultPath: string, userId: string, relativePath: string): Promise<string> {
+  return readWikiFileInRoots(vaultPath, allowedRoots(vaultPath, userId), relativePath);
+}
+
+export type WikiGrepMatch = { path: string; line: number; text: string };
+
+/** Searches every file under `roots` for `pattern` (a regular expression), line by line. */
+export async function grepWikiInRoots(vaultPath: string, roots: string[], pattern: string): Promise<WikiGrepMatch[]> {
+  const regex = new RegExp(pattern);
+  const files = await listWikiFilesInRoots(vaultPath, roots);
+  const matches: WikiGrepMatch[] = [];
+
+  for (const file of files) {
+    const content = await readWikiFileInRoots(vaultPath, roots, file);
+    const lines = content.split("\n");
+    lines.forEach((text, index) => {
+      if (regex.test(text)) {
+        matches.push({ path: file, line: index + 1, text });
+      }
+    });
+  }
+
+  return matches;
+}
+
+/** Searches every file visible to `userId` for `pattern` (a regular expression), line by line. */
+export async function grepWiki(vaultPath: string, userId: string, pattern: string): Promise<WikiGrepMatch[]> {
+  return grepWikiInRoots(vaultPath, allowedRoots(vaultPath, userId), pattern);
+}
+
+/** Reads index.md at the vault root; empty string if it doesn't exist yet (a brand-new vault, or one where self-review hasn't created it). */
+export async function readIndexFile(vaultPath: string): Promise<string> {
+  try {
+    return await readFile(resolve(vaultPath, "index.md"), "utf-8");
+  } catch {
+    return "";
+  }
+}

package/src/wiki/wiki-tools.ts

@@ -0,0 +1,112 @@
+/**
+ * Model-invocable wiki tools (`list_files`/`read_file`/`write_file`/
+ * `grep`, per SPEC.md's Layer 2), wrapping the plain functions in
+ * wiki-read.ts and wiki-note.ts in `tool()` — same split as
+ * cli-executor.ts/cli-tool.ts for the external CLIs. `write_file` only
+ * ever reaches `writeCuratedNote`: `writeInferredNote` is deliberately
+ * never wired into a tool here, since inferred/ is written exclusively
+ * by the deterministic consolidation engine, never by model
+ * choice. Every `execute` returns `{ ok, ... }` instead of throwing, so
+ * a rejected/invalid call is a self-correctable model turn, not a
+ * crashed tool call.
+ */
+import { resolve } from "node:path";
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+import { tool } from "ai";
+import { z } from "zod";
+import { listWikiFiles, readWikiFile, grepWiki, readWikiFileInRoots } from "./wiki-read.ts";
+import { writeCuratedNote } from "./wiki-note.ts";
+
+export type WikiToolsDeps = { vaultPath: string; userId: string };
+
+/** Builds the four wiki tools scoped to `deps.userId` (curated/ fully, only their own inferred/users/<userId>/). */
+export function createWikiTools(
+  deps: WikiToolsDeps,
+): Record<"list_files" | "read_file" | "write_file" | "grep" | "resolve_reference", ExecutableTool> {
+  const { vaultPath, userId } = deps;
+
+  const list_files = tool({
+    description:
+      "List every wiki document visible to you: all of curated/ (team knowledge) plus your own inferred/ " +
+      "semantic notes for the current user. Other users' inferred notes are never listed. Returns paths " +
+      "relative to the vault root.",
+    inputSchema: z.object({}),
+    execute: async () => {
+      const files = await listWikiFiles(vaultPath, userId);
+      return { ok: true as const, files };
+    },
+  });
+
+  const read_file = tool({
+    description:
+      'Read a wiki document by path (relative to the vault root, e.g. "curated/standards/jira-fields.md" or ' +
+      '"inferred/users/<your userId>/some-topic.md"). Only curated/ and your own inferred/ notes are readable.',
+    inputSchema: z.object({ path: z.string().min(1) }),
+    execute: async ({ path }) => {
+      try {
+        const content = await readWikiFile(vaultPath, userId, path);
+        return { ok: true as const, content };
+      } catch (err) {
+        return { ok: false as const, error: String(err) };
+      }
+    },
+  });
+
+  const write_file = tool({
+    description:
+      'Write or update a curated wiki document (team knowledge — conventions, standards, decisions). "path" ' +
+      'is relative to curated/, e.g. "standards/jira-fields.md". This can only write under curated/ — your ' +
+      "own semantic notes are managed automatically by the memory consolidation process, not through this tool.",
+    inputSchema: z.object({ path: z.string().min(1), content: z.string() }),
+    execute: async ({ path, content }) => {
+      try {
+        await writeCuratedNote(vaultPath, path, { last_updated: new Date().toISOString().slice(0, 10) }, content);
+        return { ok: true as const };
+      } catch (err) {
+        return { ok: false as const, error: String(err) };
+      }
+    },
+  });
+
+  const grep = tool({
+    description:
+      "Search wiki documents (curated/ plus your own inferred/ notes) for a regular expression pattern. " +
+      "Returns matching lines with their file path and line number.",
+    inputSchema: z.object({ pattern: z.string().min(1) }),
+    execute: async ({ pattern }) => {
+      try {
+        const matches = await grepWiki(vaultPath, userId, pattern);
+        return { ok: true as const, matches };
+      } catch (err) {
+        return { ok: false as const, error: String(err) };
+      }
+    },
+  });
+
+  // Deliberately not built on listWikiFiles/readWikiFile/grepWiki's
+  // allowedRoots (curated/ + inferred/users/<userId>/) — inferred/confirmations/
+  // is a different subtree on purpose, invisible to list_files/read_file/grep
+  // (see ConfirmationFrontmatterSchema's doc comment). Scoped to the calling
+  // userId's own root only, via readWikiFileInRoots directly, so a token
+  // string that happens to collide with another user's is still unreachable.
+  const resolve_reference = tool({
+    description:
+      "Resolve an opaque [REQ:<token>] reference (e.g. one you see in your own context) into the confirmation " +
+      "request it points to — a past action that required explicit confirmation, and whether it was confirmed, " +
+      "failed, or is still pending. If it's still pending, ask the user whether they still want it done — never " +
+      "re-run the command yourself without them explicitly saying so.",
+    inputSchema: z.object({ token: z.string().min(1) }),
+    execute: async ({ token }) => {
+      try {
+        const userRoot = resolve(vaultPath, "inferred", "confirmations", encodeURIComponent(userId));
+        const relativePath = `inferred/confirmations/${encodeURIComponent(userId)}/${token}.md`;
+        const content = await readWikiFileInRoots(vaultPath, [userRoot], relativePath);
+        return { ok: true as const, content };
+      } catch (err) {
+        return { ok: false as const, error: String(err) };
+      }
+    },
+  });
+
+  return { list_files, read_file, write_file, grep, resolve_reference };
+}