obsidian-mcp-server 3.5.3 → 3.5.5

package/dist/services/obsidian/obsidian-service.js

@@ -4,11 +4,12 @@
  * `target` discriminator, and classifies errors for the framework.
  * @module services/obsidian/obsidian-service
  */
-import { conflict, forbidden, JsonRpcErrorCode, McpError, notFound, serviceUnavailable, unauthorized, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { configurationError, conflict, forbidden, JsonRpcErrorCode, McpError, notFound, serviceUnavailable, unauthorized, validationError, } from '@cyanheads/mcp-ts-core/errors';
 import { httpStatusToErrorCode, withRetry } from '@cyanheads/mcp-ts-core/utils';
 import { Agent, fetch as undiciFetch } from 'undici';
 import { getServerConfig } from '../../config/server-config.js';
 import { PathPolicy } from './path-policy.js';
+import { listHeadingPaths } from './section-extractor.js';
 /** Per-call timeout for the startup probe — covers the 4-tuple TCP handshake + a tiny GET. */
 const OMNISEARCH_PROBE_TIMEOUT_MS = 500;
 /**
@@ -44,12 +45,58 @@ const MARKDOWN_PATCH_VERSION_HEADER = 'Markdown-Patch-Version';
 const MARKDOWN_PATCH_VERSION = '1';
 /** Delimiter joining ancestor headings into a single PATCH heading target. */
 const HEADING_DELIMITER = '::';
+/**
+ * The suffix markdown-patch 2.0 appends to the key of the second and later
+ * occurrences of a sibling heading: U+FC750, then the occurrence index minus
+ * one in hex, each digit written as one of U+F6440–U+F644F. The plugin refuses
+ * a note whose own heading text ends this way, so stripping it is exact.
+ */
+const DUPLICATE_SUFFIX = /\u{FC750}[\u{F6440}-\u{F644F}]+$/u;
 /**
  * Methods safe to retry on transient errors. POST/PATCH are excluded — a
  * successful upstream write with a lost response would double-apply on retry
  * (duplicate `append`, re-run Obsidian command).
  */
 const RETRY_SAFE_METHODS = new Set(['GET', 'PUT', 'DELETE']);
+/**
+ * Codes a TLS stack reports when it refuses the server's certificate. Both
+ * runtimes use OpenSSL's names. The first four were each produced on Bun 1.4.0
+ * and Node 26.5.0 (a self-signed leaf, an untrusted issuer, a SAN mismatch, an
+ * expired leaf); the rest are the same verifier's documented neighbours.
+ */
+const CERTIFICATE_REJECTION_CODES = new Set([
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'ERR_TLS_CERT_ALTNAME_INVALID',
+    'CERT_HAS_EXPIRED',
+    'CERT_NOT_YET_VALID',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+]);
+/**
+ * Codes for a connection that failed before any response. Node reports errno
+ * names plus undici's own (`UND_ERR_SOCKET` is a socket closed with no bytes);
+ * Bun reports a refused connection as the non-errno `ConnectionRefused` and the
+ * others by errno name. Refused, host-not-found, and reset were produced on
+ * both runtimes; the unreachable-network and connect-timeout codes are the same
+ * failure reached over a route that drops packets instead of refusing them.
+ */
+const CONNECTION_FAILURE_CODES = new Set([
+    'ECONNREFUSED',
+    'ConnectionRefused',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ECONNRESET',
+    'UND_ERR_SOCKET',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+/**
+ * Route prefixes that address a note. An error on one of these echoes the
+ * caller's note under `data.path`; no other route carries a vault path.
+ */
+const NOTE_ROUTE_PREFIXES = ['/vault/', '/open/', '/active/', '/periodic/'];
 export class ObsidianService {
     #config;
     #dispatcher;
@@ -73,16 +120,10 @@ export class ObsidianService {
         this.#policy = new PathPolicy(config);
         this.#omnisearchUrl = deriveOmnisearchUrl(config);
         /**
-         * Bun's runtime ignores undici's per-dispatcher `connect.rejectUnauthorized`
-         * option, so the only reliable opt-out under Bun is the process-wide
-         * `NODE_TLS_REJECT_UNAUTHORIZED=0` flag. Node honors the dispatcher option
-         * (set below), so the env var fallback is scoped to Bun to avoid mutating
-         * process-wide TLS behavior on Node. Default Obsidian Local REST API ships
-         * a self-signed cert, so most users run with `OBSIDIAN_VERIFY_SSL=false`.
+         * Node honors this dispatcher option and ignores the per-request `tls` one;
+         * Bun's `fetch` does the reverse. Both are sent on every request (see
+         * `#tlsInit`), so one code path covers both runtimes with no runtime sniff.
          */
-        if (!config.verifySsl && typeof globalThis.Bun !== 'undefined') {
-            process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-        }
         this.#dispatcher = new Agent({
             connect: { rejectUnauthorized: config.verifySsl },
             headersTimeout: config.requestTimeoutMs,
@@ -98,6 +139,19 @@ export class ObsidianService {
     get omnisearchUrl() {
         return this.#omnisearchUrl;
     }
+    /**
+     * Close the undici dispatcher, releasing its keep-alive sockets to the Local
+     * REST API and Omnisearch. Wired through `createApp({ teardown })`; waits for
+     * in-flight requests to settle rather than aborting them.
+     *
+     * Bun resolves `undici` to a built-in shim whose `Agent` is an inert object
+     * with no `close` — Bun's `fetch` pools sockets itself and ignores the
+     * dispatcher — so there is nothing to release there.
+     */
+    async close() {
+        const dispatcher = this.#dispatcher;
+        await dispatcher.close?.();
+    }
     // ── Status ───────────────────────────────────────────────────────────────
     /**
      * The plugin's root capability report: reachability, versions, manifest, and
@@ -245,16 +299,15 @@ export class ObsidianService {
             this.#policy.assertReadable(target.path);
         }
         const url = this.#targetToPath(target);
-        const res = await this.#fetch(`${this.#config.baseUrl}${url}`, {
+        const requestUrl = `${this.#config.baseUrl}${url}`;
+        const res = await this.#send(ctx, requestUrl, {
             method: 'HEAD',
             headers: { Authorization: `Bearer ${this.#config.apiKey}` },
-            dispatcher: this.#dispatcher,
-            signal: ctx.signal,
         });
         if (res.status === 404)
             return null;
         if (!res.ok)
-            await this.#throwForStatus(res, url, ctx);
+            await this.#throwForStatus(res, url, ctx, { requestedUrl: requestUrl });
         this.#assertNotDirectory(res, url, ctx);
         return parseContentLength(res, url);
     }
@@ -307,11 +360,15 @@ export class ObsidianService {
     }
     // ── Search ───────────────────────────────────────────────────────────────
     /**
-     * Text search. The upstream materializes one context window per matching
-     * note before it responds, so an oversized `contextLength` on a broad query
-     * exhausts V8's string capacity and comes back as an opaque 500 — caught
-     * here and re-thrown typed, the way `searchOmnisearch` re-throws its own
-     * reachability failure.
+     * Text search. Each upstream span gets its `context` offsets resolved
+     * (`contextRelativeSpan`), then a multi-token query's spans are merged into
+     * match locations (`mergeIntoLocations`).
+     *
+     * The upstream materializes one context window per matching note before it
+     * responds, so an oversized `contextLength` on a broad query exhausts V8's
+     * string capacity and comes back as an opaque 500 — caught here and
+     * re-thrown typed, the way `searchOmnisearch` re-throws its own reachability
+     * failure.
      */
     async searchText(ctx, query, contextLength = 100) {
         const params = new URLSearchParams({ query, contextLength: String(contextLength) });
@@ -335,15 +392,13 @@ export class ObsidianService {
             }, { cause: err });
         }
         const raw = (await res.json());
+        const tokens = queryTokens(query);
         // Upstream returns a constant `score` that carries no ranking signal for
         // text mode — drop it on the way out so consumers don't mistake it for
         // relevance. Omnisearch is the source of real BM25 ranking.
         return raw.map((h) => ({
             filename: h.filename,
-            matches: h.matches.map((m) => ({
-                context: m.context,
-                match: { ...m.match, ...contextRelativeSpan(m, h.filename, contextLength, query) },
-            })),
+            matches: mergeIntoLocations(h.matches.map((m) => contextRelativeSpan(m, h.filename, contextLength, tokens)), tokens.length, contextLength).map(({ context, match }) => ({ context, match })),
         }));
     }
     async searchJsonLogic(ctx, logic) {
@@ -365,10 +420,12 @@ export class ObsidianService {
      */
     async probeOmnisearch(signal) {
         const probeSignal = signal ?? AbortSignal.timeout(OMNISEARCH_PROBE_TIMEOUT_MS);
+        const url = `${this.#omnisearchUrl}/search?q=`;
         try {
-            const res = await this.#fetch(`${this.#omnisearchUrl}/search?q=`, {
+            const res = await this.#fetch(url, {
                 method: 'GET',
                 dispatcher: this.#dispatcher,
+                ...this.#tlsInit(url),
                 signal: probeSignal,
             });
             if (!res.ok)
@@ -398,6 +455,7 @@ export class ObsidianService {
             res = await this.#fetch(url, {
                 method: 'GET',
                 dispatcher: this.#dispatcher,
+                ...this.#tlsInit(url),
                 signal: ctx.signal,
             });
         }
@@ -498,31 +556,86 @@ export class ObsidianService {
      * leaf name reaches the same section on writes that it already reaches on
      * reads. `extractSection` matches a heading at any depth, so an agent that
      * read `## Sibling` by its bare name carries that name to a write, where
-     * upstream targeting wants the whole `Parent::Child` chain.
+     * upstream targeting wants the whole `Parent::Child` chain. Locators that
+     * already carry the delimiter pass through unexpanded; non-heading targets
+     * skip resolution entirely.
      *
-     * Resolution order: an exact map entry wins (preserving upstream's own
-     * interpretation), then a unique leaf match is expanded, then several leaf
-     * matches are rejected as ambiguous rather than silently writing to the first.
-     * A leaf absent from the map passes through untouched so
-     * `Create-Target-If-Missing` still creates it and the upstream's own
-     * target-miss error still surfaces. Non-heading targets and locators that
-     * already carry the delimiter skip the lookup entirely.
+     * The resolved path must then name exactly one heading. The 1.x map the
+     * PATCH resolves against keys headings by full path, so a path that repeats
+     * in the note is listed once, at its last occurrence — the PATCH would land
+     * on the last repeat while a section read returns the first. A write to a
+     * repeated path is rejected as ambiguous. The count comes from the plugin's
+     * own parse (`#headingIndex`), not a local scan: the two disagree on
+     * headings inside list items, HTML blocks, and setext underlines, and a local
+     * count there rejected writes the PATCH would have landed correctly.
      */
     async #resolveHeadingTarget(ctx, target, headers) {
-        if (headers.targetType !== 'heading' || headers.target.includes(HEADING_DELIMITER)) {
+        if (headers.targetType !== 'heading')
             return headers.target;
+        const { headings, occurrences } = await this.#headingIndex(ctx, target);
+        const resolved = headers.target.includes(HEADING_DELIMITER)
+            ? headers.target
+            : this.#expandHeadingLeaf(target, headers.target, headings);
+        const repeats = occurrences.filter((p) => p === resolved);
+        if (repeats.length <= 1)
+            return resolved;
+        const display = displayPath(this.#targetToPath(target));
+        const named = resolved === headers.target ? `'${resolved}'` : `'${headers.target}' (${resolved})`;
+        throw conflict(`Heading ${named} occurs ${repeats.length} times in ${display}, so a section write cannot tell which one to edit.`, {
+            path: display,
+            reason: 'ambiguous_section',
+            candidates: repeats,
+            recovery: {
+                hint: `Every heading in \`candidates\` has the same full path, so no section locator picks one. Rename all but one of them so each path is unique — obsidian_replace_in_note can rewrite a heading line — then retry. obsidian_get_note with format "section" reads the first occurrence.`,
+            },
+        });
+    }
+    /**
+     * The note's heading paths as the plugin parses them, in one request:
+     * `headings` lists each distinct path the way the 1.x document map does
+     * (what a leaf expands against), and `occurrences` lists every heading,
+     * repeats included (what the repeat count reads).
+     *
+     * Both come from the markdown-patch 2.0 document map, whose tree keeps a key
+     * per repeat; flattened with the repeat suffixes stripped and collapsed, it
+     * is the 1.x `headings` array exactly, since both formats read the same
+     * parser's top-level heading tokens. Plugin v4.x ignores the version header
+     * and answers with the 1.x array, which cannot count repeats, so there the
+     * note body is fetched and scanned locally (`listHeadingPaths`).
+     */
+    async #headingIndex(ctx, target) {
+        const res = await this.#request(ctx, this.#targetToPath(target), {
+            method: 'GET',
+            headers: { Accept: DOCUMENT_MAP_ACCEPT, [MARKDOWN_PATCH_VERSION_HEADER]: '2' },
+            noteRead: true,
+        });
+        const map = (await res.json());
+        if (Array.isArray(map.headings)) {
+            const { content } = await this.#rawGetNoteJson(ctx, target);
+            return { headings: map.headings, occurrences: listHeadingPaths(content) };
         }
-        const map = await this.#rawGetDocumentMap(ctx, target);
-        if (map.headings.includes(headers.target))
-            return headers.target;
-        const matches = map.headings.filter((h) => h.split(HEADING_DELIMITER).pop() === headers.target);
+        const occurrences = flattenHeadingTree(map.headings);
+        return { headings: [...new Set(occurrences)].filter(Boolean), occurrences };
+    }
+    /**
+     * Expand a bare heading leaf against the note's heading paths. Resolution
+     * order: an exact entry wins (preserving upstream's own interpretation),
+     * then a unique leaf match is expanded, then several leaf matches are
+     * rejected as ambiguous rather than silently writing to the first. A leaf
+     * absent from the paths passes through untouched so `Create-Target-If-Missing`
+     * still creates it and the upstream's own target-miss error still surfaces.
+     */
+    #expandHeadingLeaf(target, leaf, headings) {
+        if (headings.includes(leaf))
+            return leaf;
+        const matches = headings.filter((h) => h.split(HEADING_DELIMITER).pop() === leaf);
         const [first] = matches;
         if (first === undefined)
-            return headers.target;
+            return leaf;
         if (matches.length === 1)
             return first;
         const display = displayPath(this.#targetToPath(target));
-        throw conflict(`Heading '${headers.target}' is ambiguous in ${display} — ${matches.length} headings share that name: ${matches.join(', ')}.`, {
+        throw conflict(`Heading '${leaf}' is ambiguous in ${display} — ${matches.length} headings share that name: ${matches.join(', ')}.`, {
             path: display,
             reason: 'ambiguous_section',
             candidates: matches,
@@ -578,6 +691,60 @@ export class ObsidianService {
             headers['Trim-Target-Whitespace'] = 'true';
         return headers;
     }
+    /**
+     * The TLS relaxation for one request, scoped to that request.
+     *
+     * `OBSIDIAN_VERIFY_SSL=false` exists because the Local REST API's always-on
+     * HTTPS port ships a self-signed certificate, so the relaxation belongs on
+     * the requests that reach it and nowhere else — a process-wide
+     * `NODE_TLS_REJECT_UNAUTHORIZED=0` would also disable verification for every
+     * unrelated HTTPS call the process makes (a JWKS fetch, say). Issue #131.
+     *
+     * Verified on Bun 1.4.0: Bun's `fetch` honors this per-request `tls` option
+     * and ignores the dispatcher, while Node's undici honors the dispatcher's
+     * `connect.rejectUnauthorized` and ignores `tls`. Sending both unconditionally
+     * is therefore correct on both, with no runtime sniffing. A plain-HTTP URL
+     * gets neither — there is no certificate to relax, and the Omnisearch leg is
+     * plain HTTP even when the vault endpoint is not.
+     *
+     * The scheme is matched case-insensitively because that is what it is: a URL
+     * schema accepts `HTTPS://…` and keeps the caller's spelling, so an exact
+     * `startsWith` reads a configured `HTTPS://` base URL as plain HTTP and
+     * withholds the relaxation the operator asked for.
+     */
+    #tlsInit(url) {
+        if (this.#config.verifySsl || !/^https:/i.test(url))
+            return {};
+        return { tls: { rejectUnauthorized: false } };
+    }
+    /**
+     * One request to the Local REST API — the single attempt `#request` hands
+     * to `withRetry`, and `tryGetSize`'s HEAD — with the dispatcher, the scoped
+     * TLS relaxation, and the caller's signal attached.
+     *
+     * A rejected `fetch` is classified here, inside the attempt, because the
+     * attempt is where the retry decision is made: a certificate rejection comes
+     * back as a non-transient `ConfigurationError` and `withRetry` rethrows it
+     * on the spot, while an unreachable plugin comes back as a transient
+     * `ServiceUnavailable` and keeps its retries (issues #133 and #136). A
+     * rejection that is neither passes through untouched, and so does anything
+     * thrown after the caller aborted — a cancellation is not a network fault.
+     */
+    async #send(ctx, url, init) {
+        try {
+            return await this.#fetch(url, {
+                ...init,
+                dispatcher: this.#dispatcher,
+                ...this.#tlsInit(url),
+                signal: ctx.signal,
+            });
+        }
+        catch (err) {
+            if (ctx.signal?.aborted)
+                throw err;
+            throw classifyFetchRejection(err) ?? err;
+        }
+    }
     #request(ctx, pathAndQuery, init) {
         const url = `${this.#config.baseUrl}${pathAndQuery}`;
         const headers = {
@@ -585,15 +752,16 @@ export class ObsidianService {
             Authorization: `Bearer ${this.#config.apiKey}`,
         };
         const exec = async () => {
-            const res = await this.#fetch(url, {
+            const res = await this.#send(ctx, url, {
                 method: init.method,
                 headers,
                 ...(init.body !== undefined ? { body: init.body } : {}),
-                dispatcher: this.#dispatcher,
-                signal: ctx.signal,
             });
             if (!res.ok) {
-                await this.#throwForStatus(res, pathAndQuery, ctx, { listRead: init.listRead });
+                await this.#throwForStatus(res, pathAndQuery, ctx, {
+                    listRead: init.listRead,
+                    requestedUrl: url,
+                });
             }
             if (init.noteRead) {
                 this.#assertNotDirectory(res, pathAndQuery, ctx);
@@ -697,10 +865,12 @@ export class ObsidianService {
     async #probeCapabilities(ctx) {
         const deadline = AbortSignal.timeout(CAPABILITY_PROBE_TIMEOUT_MS);
         try {
-            const res = await this.#fetch(`${this.#config.baseUrl}/`, {
+            const url = `${this.#config.baseUrl}/`;
+            const res = await this.#fetch(url, {
                 method: 'GET',
                 headers: { Authorization: `Bearer ${this.#config.apiKey}` },
                 dispatcher: this.#dispatcher,
+                ...this.#tlsInit(url),
                 signal: ctx.signal ? AbortSignal.any([ctx.signal, deadline]) : deadline,
             });
             if (!res.ok)
@@ -715,10 +885,12 @@ export class ObsidianService {
      * Classify an upstream error response and throw.
      *
      * **Containment invariant.** Four things leave this method on the wire and
-     * nothing else: a message authored in this file, the request path the caller
-     * supplied (`data.path`), the HTTP status (`data.status`, default branch),
-     * and the calling tool's own contract `reason` + `recovery`. The upstream's
-     * response body never crosses, in any branch, under any key.
+     * nothing else: a message authored in this file, the caller's own identifier
+     * (`data.path` on a note route, `data.commandId` on a command, neither on a
+     * route that carries no caller input — see `callerIdentifier`), the HTTP
+     * status (`data.status`, default branch), and the calling tool's own
+     * contract `reason` + `recovery`. The upstream's response body never
+     * crosses, in any branch, under any key.
      *
      * That is stricter than redaction, deliberately. The Local REST API
      * interleaves genuine diagnostics with vault data in one string: a rejected
@@ -742,17 +914,25 @@ export class ObsidianService {
      * envelope is built from `code`/`message`/`data` alone, and so is the
      * JSON-RPC error object the SDK emits for resources.
      *
-     * Issues #104 and #116.
+     * `opts.requestedUrl` — the absolute URL actually fetched — rides the same
+     * channel for the same reason. `path` stays the vault route both call sites
+     * supply: the branches below classify on its prefix and `displayPath()`
+     * renders it as the caller wrote it, while the base URL is deployment detail
+     * that has no place on the wire. It does belong in the log, though, since a
+     * malformed `OBSIDIAN_BASE_URL` is otherwise invisible behind a clean-looking
+     * 404 (issue #122).
+     *
+     * Issues #104, #116, and #122.
      */
-    async #throwForStatus(res, path, ctx, opts = {}) {
+    async #throwForStatus(res, path, ctx, opts) {
         const text = await this.#readBodySafe(res);
         const body = parseJsonObject(text);
         const display = displayPath(path);
         /** Classification input and log payload only — never a wire value. */
         const upstreamMsg = typeof body?.message === 'string' ? body.message : text.trim();
-        const cause = new UpstreamErrorText(upstreamMsg);
+        const cause = new UpstreamErrorText(upstreamMsg, opts.requestedUrl);
         const data = (reason) => ({
-            path: display,
+            ...callerIdentifier(path),
             ...(reason !== undefined ? { reason, ...ctx.recoveryFor(reason) } : {}),
         });
         switch (res.status) {
@@ -915,54 +1095,199 @@ export function encodeVaultPath(path) {
     return segments.map((seg) => encodeURIComponent(seg)).join('/');
 }
 /**
- * Locate the match span inside the `context` window the upstream ships with it.
+ * Every heading in a markdown-patch 2.0 heading tree as its `::`-joined full
+ * path, in tree order, one entry per occurrence. A top-level untitled heading
+ * is `""`, and its children read `::Child`, as the 1.x map writes them.
+ */
+function flattenHeadingTree(tree, parent) {
+    return Object.entries(tree).flatMap(([key, children]) => {
+        const text = key.replace(DUPLICATE_SUFFIX, '');
+        const path = parent === undefined ? text : `${parent}${HEADING_DELIMITER}${text}`;
+        return [path, ...flattenHeadingTree(children, path)];
+    });
+}
+/**
+ * The query as Obsidian's `prepareSimpleSearch` reads it: split on whitespace,
+ * case-folded, each distinct token required. Quotes are ordinary characters.
+ */
+function queryTokens(query) {
+    return [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
+}
+const isHighSurrogate = (cu) => cu >= 0xd800 && cu <= 0xdbff;
+const isLowSurrogate = (cu) => cu >= 0xdc00 && cu <= 0xdfff;
+/**
+ * Locate the match span inside the `context` window the upstream ships with
+ * it, and name the subject its `start`/`end` index.
  *
- * `start`/`end` are offsets into whichever subject the plugin matched, and
- * there are two. For a **body match** the subject is the note text and the
- * window is `body.slice(max(0, start - contextLength), min(len, end + contextLength))`,
+ * There are two subjects. For a **body match** the subject is the note text
+ * and the window is `body.slice(max(0, start - contextLength), end + contextLength)`,
  * so the span sits `min(start, contextLength)` characters into `context`. For a
  * **filename match** the subject is the note's basename and the plugin returns
  * that basename whole as `context`, so the span sits at `start` — which runs
  * past `min(start, contextLength)` as soon as the name is longer than the
- * window. A single hit's `matches[]` can carry both kinds. Verified against
- * Local REST API v5.0.3.
+ * window. A single hit's `matches[]` can carry both kinds.
  *
- * `context === basename` is the cheap separator, but it is not decisive: a body
- * window whose left edge is trimmed can coincide with the basename (a note whose
- * own name is quoted in its body, matched so the window lands on that quote),
- * and then the two readings disagree and the filename one slices the wrong text
- * — often past the end of `context` entirely. Where they disagree, settle it on
- * the text rather than the coincidence: the plugin matches whole query tokens,
- * so the correct reading reproduces one. An inconclusive check keeps the
- * filename reading, which is what the coincidence test alone would have picked.
+ * `match.source` (`"filename"` / `"content"`, plugin 5.0.3+) names the subject
+ * outright. Without it, `context === basename` is the cheap separator, but it
+ * is not decisive: a body window whose left edge is trimmed can coincide with
+ * the basename (a note whose own name is quoted in its body), and then the two
+ * readings disagree. Where they do, the text settles it — the correct reading
+ * reproduces the match — and an inconclusive check keeps the filename reading.
+ *
+ * Plugin 5.1.0+ widens a body window by one code unit rather than split a
+ * surrogate pair (`widenToCodePointBoundaries`), so the window can start one
+ * character before `start - contextLength` — see `bodyWindowOffset`.
  */
-function contextRelativeSpan(m, filename, contextLength, query) {
-    const span = m.match.end - m.match.start;
-    const bodyStart = Math.min(m.match.start, contextLength);
+function contextRelativeSpan(m, filename, contextLength, tokens) {
+    const { start, end, source } = m.match;
+    const span = end - start;
+    const at = (subject, i) => ({
+        context: m.context,
+        match: { start, end, contextStart: i, contextEnd: i + span },
+        subject,
+    });
+    /**
+     * The matched text is a run of coalesced token occurrences, so it opens with
+     * one token and closes with one. A reading shifted by a character fails
+     * that: upstream reports every occurrence, so a token beginning one
+     * character early, or ending one character late, would have been coalesced
+     * into this span already.
+     */
+    const reproduces = (i) => {
+        const slice = m.context.slice(i, i + span).toLowerCase();
+        return (slice.length === span &&
+            tokens.some((t) => slice.startsWith(t)) &&
+            tokens.some((t) => slice.endsWith(t)));
+    };
+    if (source === 'filename')
+        return at('filename', start);
+    const bodyStart = bodyWindowOffset(m, contextLength, reproduces);
+    if (source === 'content')
+        return at('body', bodyStart);
     const basename = (filename.split('/').pop() ?? filename).replace(/\.[^./]+$/, '');
-    const at = (i) => ({ contextStart: i, contextEnd: i + span });
-    if (m.context !== basename || m.match.start === bodyStart)
-        return at(bodyStart);
-    const reproducesToken = (i) => {
-        const slice = m.context.slice(i, i + span);
-        return slice.length === span && query.toLowerCase().includes(slice.toLowerCase());
+    if (m.context !== basename)
+        return at('body', bodyStart);
+    if (start === bodyStart)
+        return at('filename', start);
+    return reproduces(start) || !reproduces(bodyStart)
+        ? at('filename', start)
+        : at('body', bodyStart);
+}
+/**
+ * Where a body match sits in its window: `min(start, contextLength)`, or one
+ * further when upstream widened the left edge to keep a surrogate pair whole.
+ *
+ * The widening happens only when the window is not clipped at the note start
+ * and its unwidened edge fell on a low surrogate, and it leaves a window that
+ * opens on a whole pair. A window that simply begins on a pair looks the same
+ * from `context` alone, so between the two candidate offsets the one that
+ * reproduces the match wins; a tie keeps the unwidened reading, which is also
+ * correct for plugins that predate the widening.
+ */
+function bodyWindowOffset(m, contextLength, reproduces) {
+    const base = Math.min(m.match.start, contextLength);
+    if (m.match.start <= contextLength)
+        return base;
+    if (!isHighSurrogate(m.context.charCodeAt(0)) || !isLowSurrogate(m.context.charCodeAt(1))) {
+        return base;
+    }
+    return !reproduces(base) && reproduces(base + 1) ? base + 1 : base;
+}
+/**
+ * Merge a hit's spans into match locations. `prepareSimpleSearch` reports one
+ * span per token occurrence and coalesces only spans that touch, so each word
+ * of a phrase arrives as its own span with a near-identical window.
+ *
+ * Walking the spans in upstream order, a location takes the next span when all
+ * of these hold:
+ *
+ * - Same subject. Body and basename offsets have different origins.
+ * - `next.start - location.end ≤ 2 × contextLength`, which is when the two
+ *   windows overlap or abut. The union window is then contiguous and no longer
+ *   than the two it replaces, so a merge never grows the response.
+ * - The location does not already hold that span's case-folded text. Without
+ *   this bound a common token chains transitively across a whole note into a
+ *   single unbounded window that counts once against `maxMatchesPerHit`.
+ * - The windows agree on the text they share. The stitch is computed from
+ *   each window's real extent, so it follows edge clipping and surrogate
+ *   widening; a disagreement means the offsets are wrong, and refusing beats
+ *   fabricating note text.
+ *
+ * A query with a single distinct token is left alone, so single-word results
+ * keep one match per occurrence.
+ */
+function mergeIntoLocations(spans, distinctTokens, contextLength) {
+    if (distinctTokens < 2)
+        return spans;
+    const locations = [];
+    let current;
+    for (const span of spans) {
+        const text = matchedText(span);
+        if (current && !current.texts.has(text)) {
+            const joined = joinLocation(current.location, span, contextLength);
+            if (joined) {
+                current.location = joined;
+                current.texts.add(text);
+                continue;
+            }
+        }
+        if (current)
+            locations.push(current.location);
+        current = { location: span, texts: new Set([text]) };
+    }
+    if (current)
+        locations.push(current.location);
+    return locations;
+}
+function matchedText(span) {
+    return span.context.slice(span.match.contextStart, span.match.contextEnd).toLowerCase();
+}
+/** `location` extended through `next`, or `undefined` when the two may not merge. */
+function joinLocation(location, next, contextLength) {
+    if (next.subject !== location.subject)
+        return;
+    const gap = next.match.start - location.match.end;
+    if (gap < 0 || gap > 2 * contextLength)
+        return;
+    /** Subject offsets of each window's first character. */
+    const left = location.match.start - location.match.contextStart;
+    const nextLeft = next.match.start - next.match.contextStart;
+    const offset = nextLeft - left;
+    const shared = location.context.length - offset;
+    if (offset < 0 || shared < 0)
+        return;
+    const head = next.context.slice(0, shared);
+    if (location.context.slice(offset, offset + head.length) !== head)
+        return;
+    return {
+        context: location.context + next.context.slice(shared),
+        match: {
+            start: location.match.start,
+            end: next.match.end,
+            contextStart: location.match.contextStart,
+            contextEnd: next.match.end - left,
+        },
+        subject: location.subject,
     };
-    return reproducesToken(m.match.start) || !reproducesToken(bodyStart)
-        ? at(m.match.start)
-        : at(bodyStart);
 }
 /**
- * The upstream error body, carried as the `cause` of everything
- * `#throwForStatus` throws.
+ * The upstream error body and the URL it answered, carried as the `cause` of
+ * everything `#throwForStatus` throws.
  *
  * `cause` is the one channel that reaches the server's logs without reaching
  * the client, which is what lets the containment invariant hold while the
- * text stays available for debugging and for the classifiers below. The body
- * is the `Error` message so the framework's cause-chain extractor records it.
+ * text stays available for debugging and for the classifiers below. Both facts
+ * go in the `Error` message so the framework's cause-chain extractor records
+ * them. Each is also kept as its own field: the classifiers match on `text`
+ * alone, so a request URL can never satisfy a pattern meant for the body.
  */
 class UpstreamErrorText extends Error {
-    constructor(text) {
-        super(text);
+    text;
+    requestedUrl;
+    constructor(text, requestedUrl) {
+        super([text, `[requested: ${requestedUrl}]`].filter(Boolean).join(' '));
+        this.text = text;
+        this.requestedUrl = requestedUrl;
         this.name = 'UpstreamErrorText';
     }
 }
@@ -976,7 +1301,7 @@ function upstreamTextOf(err) {
     let current = err;
     for (let depth = 0; depth < 4; depth++) {
         if (current instanceof UpstreamErrorText)
-            return current.message;
+            return current.text;
         if (!(current instanceof Error))
             return;
         current = current.cause;
@@ -1059,6 +1384,65 @@ function periodOf(urlPath) {
 function routeOf(urlPath) {
     return urlPath.split('?')[0] ?? urlPath;
 }
+/**
+ * The caller's identifier for an error on `urlPath`, keyed by the input it
+ * echoes — the same convention `nameRegex` and `contextLength` follow. A note
+ * route carries the note as `path`; `/commands/<id>/` carries the ID as
+ * `commandId`, which is what `obsidian_execute_command` calls it. Every other
+ * route (`/`, `/tags/`, `/commands/`, `/search/`, `/search/simple/`) carries
+ * no caller identifier, so it gets no key — `path` there used to hold the
+ * route string itself, which names no note (issue #130).
+ */
+function callerIdentifier(urlPath) {
+    if (NOTE_ROUTE_PREFIXES.some((prefix) => urlPath.startsWith(prefix))) {
+        return { path: displayPath(urlPath) };
+    }
+    if (/^\/commands\/[^/]+\/?$/.test(routeOf(urlPath))) {
+        return { commandId: displayPath(urlPath) };
+    }
+    return {};
+}
+/**
+ * Classify a rejected `fetch` — one that produced no response at all — or
+ * return `undefined` to leave it as thrown.
+ *
+ * The two runtimes put the code in different places: Bun on the thrown error
+ * itself, Node's undici one level down on `cause` under a bare `TypeError:
+ * fetch failed`. Both levels are read, and the result is built from the code
+ * alone, so a Bun and a Node rejection produce the same message and `data`.
+ * Neither the runtime's own text nor the URL it names reaches the wire; the
+ * rejection rides as `cause`, the channel `#throwForStatus` uses for the same
+ * reason.
+ *
+ * The recovery hint is written inline, as `encodeVaultPath` writes
+ * `path_traversal`'s: both failures are the operator's to fix and reachable
+ * from every tool and resource — including the two resources that declare no
+ * `errors[]` for `ctx.recoveryFor` to resolve against.
+ */
+function classifyFetchRejection(err) {
+    const codes = [err, err instanceof Error ? err.cause : undefined].flatMap((e) => {
+        const code = e?.code;
+        return typeof code === 'string' ? [code] : [];
+    });
+    const certificate = codes.find((code) => CERTIFICATE_REJECTION_CODES.has(code));
+    if (certificate !== undefined) {
+        return configurationError(`The Obsidian Local REST API's TLS certificate failed verification (${certificate}).`, {
+            reason: 'certificate_rejected',
+            recovery: {
+                hint: "OBSIDIAN_VERIFY_SSL=true accepts only a certificate this runtime trusts, and the Local REST API's HTTPS port serves a self-signed one by default. Set OBSIDIAN_VERIFY_SSL=false, or point OBSIDIAN_BASE_URL at the plugin's plain-HTTP port (27123 by default).",
+            },
+        }, { cause: err });
+    }
+    if (codes.some((code) => CONNECTION_FAILURE_CODES.has(code))) {
+        return serviceUnavailable('Could not connect to the Obsidian Local REST API.', {
+            reason: 'obsidian_unreachable',
+            recovery: {
+                hint: 'Confirm Obsidian is running with the Local REST API plugin enabled, and that OBSIDIAN_BASE_URL names the host and port the plugin listens on.',
+            },
+        }, { cause: err });
+    }
+    return;
+}
 /**
  * Convert an internal URL path (e.g. `/vault/Projects/My%20Note.md`) to the
  * vault-relative form a caller would recognize. Used in error messages so the