@mercury-fw/core 0.25.0

package/src/session/tool-log-buffer.ts

@@ -0,0 +1,73 @@
+/**
+ * Bounded, process-wide history of tool calls across both channels,
+ * scoped by session so a recall of "what did you do" only ever surfaces
+ * one conversation's own history. Originally built for the admin panel's
+ * Tool-log tab (still a consumer, unfiltered); now also backs the
+ * `recall_tool_calls` model tool (`tool-log-recall-tool.ts`), which is why
+ * this lives in `session/` rather than `admin/` — it's the record of what
+ * happened in a session, not an admin-only concern. Nothing else keeps
+ * this beyond the current turn (`src/index.ts`'s terminal-only `lastSteps`
+ * resets every turn, Google Chat's `onStepFinish` only logs to stderr) —
+ * `recordStep` is called additively from both channels' existing
+ * `onStepFinish` wiring, changing neither channel's own behavior.
+ */
+import { truncateForDisplay } from "../router/tool-log.ts";
+import type { StepInfo } from "./step-info.ts";
+
+/**
+ * Whatever the provider that ran the turn calls itself — see
+ * `InboundTurn.channel` in `src/router/provider.ts`. Was a closed union
+ * ("terminal" | "google-chat") back when the set of providers was fixed in
+ * this file; widened so a new provider is a new `Provider` implementation,
+ * not an edit here.
+ */
+export type ToolLogChannel = string;
+
+export type ToolLogEntry = {
+  timestamp: string;
+  channel: ToolLogChannel;
+  sessionKey: string;
+  toolName: string;
+  input: string;
+  output: string;
+};
+
+const MAX_ENTRIES = 200;
+const MAX_CHARS = 2000;
+
+let buffer: ToolLogEntry[] = [];
+
+export function recordStep(channel: ToolLogChannel, sessionKey: string, step: StepInfo): void {
+  for (const call of step.toolCalls) {
+    const result = step.toolResults.find((r) => r.toolCallId === call.toolCallId);
+    const errorPart = step.content.find((p) => p.type === "tool-error" && p.toolCallId === call.toolCallId);
+    const output = result
+      ? truncateForDisplay(result.output, MAX_CHARS)
+      : errorPart
+        ? `[error] ${truncateForDisplay(errorPart.error, MAX_CHARS)}`
+        : "(none)";
+
+    buffer.push({
+      timestamp: new Date().toISOString(),
+      channel,
+      sessionKey,
+      toolName: call.toolName,
+      input: truncateForDisplay(call.input, MAX_CHARS),
+      output,
+    });
+    if (buffer.length > MAX_ENTRIES) {
+      buffer.shift();
+    }
+  }
+}
+
+/** Most recent entries first, optionally restricted to one session. */
+export function getToolLog(filter?: { sessionKey?: string }): ToolLogEntry[] {
+  const matching = filter?.sessionKey ? buffer.filter((e) => e.sessionKey === filter.sessionKey) : buffer;
+  return [...matching].reverse();
+}
+
+/** Test-only: clears the module-level buffer so tests don't leak into each other. */
+export function resetToolLogForTest(): void {
+  buffer = [];
+}

package/src/session/tool-log-recall-tool.ts

@@ -0,0 +1,38 @@
+/**
+ * Model-invocable recall of this conversation's own past tool calls —
+ * same split as `wiki-tools.ts` wrapping plain functions in `tool()`.
+ * Exists because `SessionHistory` (`history.ts`) only ever persists the
+ * final assistant text of a turn, never the tool-call trace: asked to
+ * recall exactly what it ran, the model otherwise has no ground truth in
+ * its own context and reconstructs a plausible-looking (and sometimes
+ * wrong) answer instead of quoting the real one. Backed by
+ * `tool-log-buffer.ts`, filtered to the calling session only — never
+ * another conversation's history.
+ */
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+import { tool } from "ai";
+import { z } from "zod";
+import { getToolLog } from "./tool-log-buffer.ts";
+
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+
+export type ToolLogRecallDeps = { sessionKey: string };
+
+export function createToolLogRecallTool(deps: ToolLogRecallDeps): { recall_tool_calls: ExecutableTool } {
+  const recall_tool_calls = tool({
+    description:
+      "Recall the tool calls (name, input, output) you actually made earlier in THIS conversation, most " +
+      "recent first. Use this whenever asked what you ran/queried/did — quote it verbatim, don't reconstruct " +
+      "from memory.",
+    inputSchema: z.object({
+      limit: z.number().int().positive().max(MAX_LIMIT).optional(),
+    }),
+    execute: async ({ limit }) => {
+      const entries = getToolLog({ sessionKey: deps.sessionKey }).slice(0, limit ?? DEFAULT_LIMIT);
+      return { ok: true as const, entries };
+    },
+  });
+
+  return { recall_tool_calls };
+}

package/src/session/tool-start-hook.ts

@@ -0,0 +1,164 @@
+/**
+ * Wraps every tool's `execute` so `onToolStart` fires the moment a call
+ * actually begins (before its result is ready), instead of the existing
+ * `onStepFinish` visibility (`tool-log.ts`) which only reports after a step
+ * already finished, and `onToolFinish` fires once it settles. Used by
+ * `src/index.ts`'s `buildTools` for every channel — both terminal and
+ * Google Chat always supply a real `onToolStart` (`TurnSink` in
+ * `router/provider.ts`), so both are always wrapped.
+ *
+ * Every wrapped tool's `execute` calls share one `chain` (below), so at
+ * most one tool call runs at a time turn-wide — the AI SDK otherwise runs
+ * a step's tool calls concurrently (`Promise.all`), which this codebase
+ * has never actually relied on; serializing keeps Google Chat's status
+ * card for a given `toolCallId` (see `google-chat-provider.ts`) from ever
+ * having to handle an overlapping in-flight card.
+ */
+import type { Tool } from "ai";
+
+// Elenco piccolo e stabile (6 tool totali oggi) — va aggiornato a mano se
+// si aggiunge un nuovo tool nominato; qualunque nome non elencato qui
+// ricade nel fallback generico, non è un errore. `grep` non è qui: ha una
+// propria etichetta ("Sto cercando…"), non ricade nel bucket "read".
+const WIKI_TOOL_CATEGORY: Record<string, "read" | "write"> = {
+  list_files: "read",
+  read_file: "read",
+  write_file: "write",
+};
+
+/**
+ * Describes, in one short user-facing sentence, what a tool call is about to do
+ * — no arguments/queries shown. A tool a plugin contributed carries its own
+ * label via `toolStatusDescribers` (keyed by tool name), so the core never
+ * decides how a plugin's tool reads — it just looks the describer up. The other
+ * tools are core functionality (wiki, grep, memory) and keep their core-coined
+ * labels until they too become internal plugins.
+ */
+export function describeToolStart(
+  toolName: string,
+  input: unknown,
+  toolStatusDescribers: Record<string, (input: unknown) => string>,
+): string {
+  const describe = toolStatusDescribers[toolName];
+  if (describe) return describe(input);
+  if (toolName === "recall_tool_calls") return "Sto consultando la memoria…";
+  if (toolName === "read_skill") return "Sto consultando le istruzioni…";
+  if (toolName === "grep") return "Sto cercando…";
+  const wikiCategory = WIKI_TOOL_CATEGORY[toolName];
+  if (wikiCategory === "read") return "Sto leggendo il wiki…";
+  if (wikiCategory === "write") return "Sto scrivendo sul wiki…";
+  return `Sto usando ${toolName}…`;
+}
+
+const MAX_DETAIL_CHARS = 300;
+
+function truncate(s: string): string {
+  return s.length <= MAX_DETAIL_CHARS ? s : `${s.slice(0, MAX_DETAIL_CHARS)}…`;
+}
+
+function stringField(input: unknown, key: string): string | undefined {
+  if (typeof input === "object" && input !== null && key in input) {
+    const v = (input as Record<string, unknown>)[key];
+    if (typeof v === "string") return v;
+  }
+  return undefined;
+}
+
+/**
+ * The actual command/input behind a tool call, for display in a status
+ * card — `describeToolStart`'s label alone doesn't say *what* ran, only
+ * which service. No markdown decoration: Google Chat cards don't render
+ * backticks as monospace, so a plain string reads better. Named per-tool
+ * (path for a file, pattern for a search, ...) rather than dumping the raw
+ * input, since that's what a human actually wants to see; only a genuinely
+ * unmapped/future tool falls back to a bounded JSON dump.
+ */
+export function describeToolDetail(toolName: string, input: unknown): string {
+  // Any CLI tool carries a `command` string, whatever its name (jiraCommand,
+  // bitbucketCommand, the residual runCommand) — show that bare command.
+  const command = stringField(input, "command");
+  if (command !== undefined) return truncate(command);
+  switch (toolName) {
+    case "grep":
+      return truncate(stringField(input, "pattern") ?? JSON.stringify(input) ?? "");
+    case "read_file":
+    case "write_file":
+      return truncate(stringField(input, "path") ?? JSON.stringify(input) ?? "");
+    case "resolve_reference":
+      return truncate(stringField(input, "token") ?? JSON.stringify(input) ?? "");
+    case "list_files":
+      return "Tutti i documenti del wiki";
+    case "recall_tool_calls":
+      return "Cronologia delle chiamate in questa conversazione";
+    default:
+      return truncate(JSON.stringify(input) ?? "");
+  }
+}
+
+// `ToolOutcome` is part of the channel `TurnSink` contract, so it lives in
+// `@mercury-fw/channel-types` and is re-exported here for the core callers that
+// import it from this module.
+export type { ToolOutcome } from "@mercury-fw/channel-types";
+import type { ToolOutcome } from "@mercury-fw/channel-types";
+
+/**
+ * Every tool in this codebase returns a uniform `{ok: true, ...}` /
+ * `{ok: false, error, ...}` shape (confirmed across `wiki-tools.ts`,
+ * `tool-log-recall-tool.ts`, `cli-tool.ts`), with `cli-tool.ts`'s
+ * confirm-required staging additionally setting `pendingConfirmation: true`
+ * without having actually run the command yet — so this classifier works
+ * for any tool without per-tool special-casing. Defaults to `"success"` for
+ * an unrecognized result shape; nothing returned by a tool today hits that
+ * branch.
+ */
+export function classifyToolResult(result: unknown): ToolOutcome {
+  if (result && typeof result === "object" && "ok" in result) {
+    const r = result as { ok?: unknown; pendingConfirmation?: unknown };
+    if (r.ok === false) return r.pendingConfirmation === true ? "pending" : "failed";
+    if (r.ok === true) return "success";
+  }
+  return "success";
+}
+
+/**
+ * Wraps every tool's `execute` to call `onToolStart` first, then run the
+ * original, then `onToolFinish` once it settles. `chain` serializes every
+ * wrapped tool sharing this one `withToolStartHook` call (i.e. one turn's
+ * worth of tools, since `buildTools` builds fresh tools per turn) — see
+ * this file's header comment for why.
+ */
+export function withToolStartHook(
+  tools: Record<string, Tool>,
+  onToolStart: (label: string, detail?: string, toolCallId?: string) => void,
+  toolStatusDescribers: Record<string, (input: unknown) => string>,
+  onToolFinish?: (toolCallId: string, outcome: ToolOutcome) => void,
+): Record<string, Tool> {
+  let chain: Promise<void> = Promise.resolve();
+  const wrapped: Record<string, Tool> = {};
+  for (const [name, t] of Object.entries(tools)) {
+    wrapped[name] = {
+      ...t,
+      execute: (input: unknown, options: { toolCallId: string }) => {
+        const label = describeToolStart(name, input, toolStatusDescribers);
+        const detail = describeToolDetail(name, input);
+        const run = chain.then(async () => {
+          onToolStart(label, detail, options.toolCallId);
+          try {
+            const result = await (t.execute as (i: unknown, o: unknown) => unknown)(input, options);
+            onToolFinish?.(options.toolCallId, classifyToolResult(result));
+            return result;
+          } catch (err) {
+            onToolFinish?.(options.toolCallId, "failed");
+            throw err;
+          }
+        });
+        chain = run.then(
+          () => undefined,
+          () => undefined,
+        );
+        return run;
+      },
+    } as Tool;
+  }
+  return wrapped;
+}

package/src/tools/display-store.ts

@@ -0,0 +1,89 @@
+/**
+ * In-memory staging area for the user-facing `display` artifacts a tool
+ * produces (see `ToolDisplay` and the formatter decorator), decoupling
+ * *producing* an artifact from *showing* it. A tool `stash`es its already-
+ * rendered artifact here and gets back a short `ref`; the model, and only
+ * the model, decides whether to actually surface it by calling the
+ * `present` tool (see `present-tool.ts`), which marks the ref via
+ * `surface`. At finalize the turn runner appends only what
+ * `takeSurfaced` returns — the artifacts the model explicitly asked to
+ * show — never the whole set unconditionally. The worst case becomes
+ * omission (the user says "show me"), never a garbled or force-appended
+ * list.
+ *
+ * Scoped by `sessionKey`, exactly like `confirmation-store.ts`: a ref
+ * minted for one session (terminal, or a given Google Chat space+sender)
+ * can't be surfaced by another. The store is created once and shared
+ * across turns, so a ref stays valid (until its TTL) for a later
+ * "show me that list again" follow-up — session-scoped, not turn-scoped.
+ */
+export type DisplayStore = {
+  /** Stashes `artifact` for `sessionKey` and returns a fresh ref. */
+  stash(sessionKey: string, artifact: string): string;
+  /** Marks `ref` to be shown at finalize. Returns `false` if it doesn't
+   * exist, belongs to a different session, or has expired. */
+  surface(sessionKey: string, ref: string): boolean;
+  /** The artifacts surfaced for `sessionKey`, in stash order. Consumes the
+   * surfaced flag (so the same artifact isn't re-appended on a later turn
+   * unless `surface` is called again) but keeps the entry until its TTL,
+   * so a still-valid ref can be surfaced again across turns. */
+  takeSurfaced(sessionKey: string): string[];
+};
+
+const DEFAULT_TTL_MS = 5 * 60_000;
+
+type Entry = { sessionKey: string; artifact: string; surfaced: boolean; expiresAt: number };
+
+export function createDisplayStore(
+  opts: { now?: () => number; ttlMs?: number; refFn?: () => string } = {},
+): DisplayStore {
+  const now = opts.now ?? (() => Date.now());
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  let counter = 0;
+  const refFn = opts.refFn ?? (() => `d${++counter}`);
+  // Insertion-ordered (Map preserves it) so takeSurfaced returns artifacts
+  // in stash order regardless of the order the model surfaced them in.
+  const entries = new Map<string, Entry>();
+
+  return {
+    stash(sessionKey, artifact) {
+      const ref = refFn();
+      entries.set(ref, { sessionKey, artifact, surfaced: false, expiresAt: now() + ttlMs });
+      return ref;
+    },
+    surface(sessionKey, ref) {
+      const entry = entries.get(ref);
+      if (!entry) {
+        return false;
+      }
+      if (entry.expiresAt <= now()) {
+        entries.delete(ref);
+        return false;
+      }
+      if (entry.sessionKey !== sessionKey) {
+        return false;
+      }
+      entry.surfaced = true;
+      return true;
+    },
+    takeSurfaced(sessionKey) {
+      const t = now();
+      const out: string[] = [];
+      // This finalize-time sweep is also where expired entries are reclaimed:
+      // the store is a process-lifetime singleton shared across sessions, so
+      // without deleting them here an un-surfaced (or never re-surfaced) stash
+      // would live forever. Deleting during Map iteration is safe.
+      for (const [ref, entry] of entries) {
+        if (entry.expiresAt <= t) {
+          entries.delete(ref);
+          continue;
+        }
+        if (entry.sessionKey !== sessionKey) continue;
+        if (!entry.surfaced) continue;
+        out.push(entry.artifact);
+        entry.surfaced = false;
+      }
+      return out;
+    },
+  };
+}

package/src/tools/present-tool.ts

@@ -0,0 +1,41 @@
+/**
+ * The `present` tool: the model's explicit "show this artifact to the user"
+ * action. A tool that produced a user-facing `display` stashed it in the
+ * `DisplayStore` (see `display-store.ts`) and returned a `ref` on the model
+ * channel; the model never sees the rendered content, only the ref. Calling
+ * `present(ref)` marks that ref to be appended to the reply at finalize.
+ *
+ * This is what shrinks the model's job from "format this list correctly"
+ * (which small models garble) to "show this list? yes/no": the artifact is
+ * always the deterministic one the formatter produced, and the model only
+ * decides whether it appears. If the model never calls `present`, nothing is
+ * shown — the right outcome for a "how many are open?" question answered in
+ * prose. Scoped to the calling session, so it can only surface its own refs.
+ */
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+import { tool } from "ai";
+import { z } from "zod";
+import type { DisplayStore } from "./display-store.ts";
+
+export type PresentToolDeps = { sessionKey: string; store: DisplayStore };
+
+export function createPresentTool(deps: PresentToolDeps): { present: ExecutableTool } {
+  const present = tool({
+    description:
+      "Show a previously produced artifact (e.g. a list of issues) to the user. Pass the `ref` a prior tool " +
+      "result returned (its `displayRef`). Call this ONLY when the user wants to see the artifact itself; if you " +
+      "are answering in prose (a count, a yes/no, a single field), do NOT call it — the artifact stays hidden.",
+    inputSchema: z.object({ ref: z.string().min(1) }),
+    execute: async ({ ref }) => {
+      if (!deps.store.surface(deps.sessionKey, ref)) {
+        return {
+          ok: false as const,
+          error: `no artifact with ref "${ref}" to present. Only pass a displayRef returned by a tool result in this conversation.`,
+        };
+      }
+      return { ok: true as const };
+    },
+  });
+
+  return { present };
+}

package/src/wiki/frontmatter-schema.ts

@@ -0,0 +1,49 @@
+/**
+ * Frontmatter schema for wiki notes, based on Open Knowledge
+ * Format (OKF — https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing):
+ * `type` is the only field OKF mandates; `source`/`confidence`/
+ * `derived_from`/`last_reviewed` are Mercury-specific extensions, the
+ * kind OKF explicitly leaves to the producer. `curated` and `inferred`
+ * are validated as separate shapes (discriminated on `type`) because
+ * only `inferred` notes carry provenance — a curated doc has no
+ * meaningful `confidence` or `derived_from`.
+ */
+import { z } from "zod";
+
+export const CuratedFrontmatterSchema = z.object({
+  type: z.literal("curated"),
+  author: z.string().optional(),
+  last_updated: z.string().optional(),
+});
+
+export const InferredFrontmatterSchema = z.object({
+  type: z.literal("inferred"),
+  source: z.literal("agent"),
+  confidence: z.enum(["low", "medium", "high"]),
+  derived_from: z.array(z.string()).min(1),
+  last_reviewed: z.string().nullable(),
+});
+
+/**
+ * A fourth category: the lifecycle of one confirm-required action, from
+ * staging through its eventual resolution — a deterministic instruction
+ * the user explicitly approved via the confirmation-token mechanism,
+ * never an autonomous LLM judgment call. Tracks a specific CLI action's
+ * own token, written once when staged (`status: "pending"`) and
+ * overwritten in place once resolved (`"confirmed"`/`"failed"`). Lives
+ * outside `inferred/users/<userId>/` (see `wiki-read.ts`'s
+ * `allowedRoots`) so it's structurally invisible to the model's own
+ * `list_files`/`grep` — reachable only via the narrow `resolve_reference`
+ * tool given the exact token (see `wiki-tools.ts`), never by browsing.
+ */
+export const ConfirmationFrontmatterSchema = z.object({
+  type: z.literal("confirmation"),
+  status: z.enum(["pending", "confirmed", "failed"]),
+  requested_at: z.string(),
+  resolved_at: z.string().nullable(),
+  command: z.string(),
+});
+
+export type CuratedFrontmatter = z.infer<typeof CuratedFrontmatterSchema>;
+export type InferredFrontmatter = z.infer<typeof InferredFrontmatterSchema>;
+export type ConfirmationFrontmatter = z.infer<typeof ConfirmationFrontmatterSchema>;

package/src/wiki/index-entry.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic index.md line management. Turns "this curated doc, with
+ * this description" into the exact `[[wikilink]]` line format
+ * `orphan-detector.ts`'s wikilink check recognizes — instead of trusting
+ * the model to freely author (and correctly reproduce, on every edit) the
+ * whole file's syntax by hand, which is what `write_index` used to do and
+ * how a doc could end up with an index.md line that still isn't
+ * recognized as a reference to it.
+ */
+
+/** Accepts any of "curated/x/y.md", "x/y.md", or "x/y" and normalizes to "x/y" — the form `[[wikilink]]`s use. */
+export function normalizeIndexKey(path: string): string {
+  let key = path.trim();
+  if (key.startsWith("curated/")) {
+    key = key.slice("curated/".length);
+  }
+  if (key.endsWith(".md")) {
+    key = key.slice(0, -".md".length);
+  }
+  return key;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function findEntryLine(lines: string[], key: string): number {
+  const re = new RegExp(`\\[\\[${escapeRegExp(key)}(\\||\\])`);
+  return lines.findIndex((line) => re.test(line));
+}
+
+function formatEntry(key: string, description: string): string {
+  return `- [[${key}]] — ${description}`;
+}
+
+/** Adds a line for `key`, or replaces its existing one in place — never duplicates an entry. */
+export function upsertIndexEntry(content: string, key: string, description: string): string {
+  const lines = content.length > 0 ? content.split("\n").filter((_, i, arr) => !(i === arr.length - 1 && arr[i] === "")) : [];
+  const newLine = formatEntry(key, description);
+
+  const idx = findEntryLine(lines, key);
+  if (idx >= 0) {
+    lines[idx] = newLine;
+  } else {
+    lines.push(newLine);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Removes `key`'s line if present; no-op otherwise. */
+export function removeIndexEntry(content: string, key: string): string {
+  const lines = content.length > 0 ? content.split("\n").filter((_, i, arr) => !(i === arr.length - 1 && arr[i] === "")) : [];
+  const idx = findEntryLine(lines, key);
+  if (idx < 0) {
+    return content;
+  }
+  lines.splice(idx, 1);
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}

package/src/wiki/orphan-detector.ts

@@ -0,0 +1,61 @@
+/**
+ * Deterministic pre-check for the self-review job (see
+ * `self-review-runner.ts`'s index/orphan pass): which curated docs are
+ * referenced by neither `index.md` nor a `[[wikilink]]` from another
+ * curated doc. Detection only — what to do about an orphan (add it to
+ * the index, add a cross-link, both) is left to the LLM's judgment;
+ * that decision can't be made deterministically.
+ */
+import { basename, resolve } from "node:path";
+import { listWikiFilesInRoots, readWikiFileInRoots, readIndexFile } from "./wiki-read.ts";
+
+/** Both `[[jira-fields]]` and `[[jira-fields|display text]]` resolve to "jira-fields". */
+function extractWikilinks(content: string): Set<string> {
+  const links = new Set<string>();
+  const regex = /\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content))) {
+    links.add(match[1]!.trim());
+  }
+  return links;
+}
+
+export async function findOrphanCuratedDocs(vaultPath: string): Promise<string[]> {
+  const curatedRoot = resolve(vaultPath, "curated");
+  const curatedFiles = await listWikiFilesInRoots(vaultPath, [curatedRoot]);
+  const indexContent = await readIndexFile(vaultPath);
+
+  const fileContents = new Map<string, string>();
+  for (const file of curatedFiles) {
+    fileContents.set(file, await readWikiFileInRoots(vaultPath, [curatedRoot], file));
+  }
+  const indexLinks = extractWikilinks(indexContent);
+
+  const orphans: string[] = [];
+  for (const file of curatedFiles) {
+    const curatedRelative = file.slice("curated/".length).replace(/\.md$/, "");
+    const base = basename(curatedRelative);
+    // index.md can mention a doc either as a plain path or as a [[wikilink]]
+    // (the Karpathy-pattern index is itself just markdown with wikilinks).
+    const referencedByIndex =
+      indexContent.includes(file) || indexLinks.has(curatedRelative) || indexLinks.has(base);
+
+    // "Referenced" means linked from ANOTHER doc — a doc's own [[self-link]]
+    // doesn't count, or every self-linking doc would wrongly stop being orphaned.
+    let referencedByLink = false;
+    for (const [otherFile, content] of fileContents) {
+      if (otherFile === file) continue;
+      const links = extractWikilinks(content);
+      if (links.has(curatedRelative) || links.has(base)) {
+        referencedByLink = true;
+        break;
+      }
+    }
+
+    if (!referencedByIndex && !referencedByLink) {
+      orphans.push(file);
+    }
+  }
+
+  return orphans.sort();
+}