obsidian-mcp-server 3.5.4 → 3.6.0

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

@@ -4,11 +4,13 @@
  * `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 { canonicalContent, flattenDocumentMap, flattenHeadingTree, hasIntegerKey, inNoteOrder, isIntegerKey, patchFormatFor, relativeHeadingLevels, v1PatchHeaders, v2Instruction, } from './patch-instruction.js';
 import { PathPolicy } from './path-policy.js';
+import { atxHeadingMarkers, blockKinds, isIsolatedBlockId, listHeadingPaths, sectionBody, sectionLevel, } 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;
 /**
@@ -26,22 +28,16 @@ const NOTE_JSON_ACCEPT = 'application/vnd.olrapi.note+json';
 const DOCUMENT_MAP_ACCEPT = 'application/vnd.olrapi.document-map+json';
 const JSONLOGIC_CT = 'application/vnd.olrapi.jsonlogic+json';
 /**
- * The markdown-patch wire format this client speaks, pinned explicitly on every
- * request whose shape depends on it: header-driven PATCH targeting and the
- * document map.
- *
- * Local REST API v5.0.0 made format 2.0 the default, rejects header-driven
- * PATCH targeting outright unless a version is pinned, and returns the document
- * map's `headings` as a nested tree instead of `::`-joined paths. Plugin v4.x
- * predates the header and only ever reads named headers it knows, so the pin is
- * inert there — one unconditional value covers the whole supported plugin
- * range, and no future default flip can move the format underneath this client.
- *
- * Format 1.x carries `Deprecation: true; sunset-version="6.0"` upstream; the
- * migration to 2.0 is tracked in #102.
+ * The header naming the markdown-patch format a request speaks, sent on every
+ * request whose shape depends on it: section-targeted PATCHes and the document
+ * map. Which value goes out is negotiated per plugin install
+ * (`#markdownPatchFormat`), and stating it rather than inheriting the plugin's
+ * default keeps a future default flip from moving the format underneath this
+ * client. Plugin v4.x predates the header and ignores it.
  */
 const MARKDOWN_PATCH_VERSION_HEADER = 'Markdown-Patch-Version';
-const MARKDOWN_PATCH_VERSION = '1';
+/** Content type of a markdown-patch 2.0 JSON instruction body. */
+const PATCH_INSTRUCTION_CT = 'application/vnd.olrapi.patch-instruction+json';
 /** Delimiter joining ancestor headings into a single PATCH heading target. */
 const HEADING_DELIMITER = '::';
 /**
@@ -50,6 +46,45 @@ const HEADING_DELIMITER = '::';
  * (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;
@@ -63,6 +98,12 @@ export class ObsidianService {
      * again rather than inheriting a transient outage forever.
      */
     #capabilities;
+    /**
+     * The markdown-patch format the installed plugin speaks, read once from its
+     * capability report. Holds the in-flight promise so concurrent writes share
+     * one read; a failed read is evicted so the next write tries again.
+     */
+    #patchFormat;
     /**
      * @param config - Validated server config (api key, base URL, TLS, timeouts).
      * @param fetchImpl - Optional fetch override for tests. Defaults to undici's
@@ -209,20 +250,36 @@ export class ObsidianService {
         });
     }
     /**
-     * Apply a header-targeted PATCH. Returns the section locator the edit was
-     * actually applied to — identical to `headers.target` unless a bare heading
-     * leaf was expanded to its full `Parent::Child` path (see
-     * `#resolveHeadingTarget`), which callers echo back so an agent can see where
-     * the write landed.
+     * Apply a section-targeted PATCH in the markdown-patch format the plugin
+     * speaks: a 2.0 JSON instruction on Local REST API 5.x and later, 1.x
+     * request headers on 4.x and for the table-row writes 2.0 cannot express
+     * (`#wireFormat`). Returns the section locator the edit was actually
+     * applied to — identical to `instruction.target` unless a bare heading leaf
+     * was expanded to its full `Parent::Child` path (see `#resolveHeadingTarget`),
+     * which callers echo back so an agent can see where the write landed.
      */
-    async patchNote(ctx, target, content, headers) {
+    async patchNote(ctx, target, content, instruction) {
         const safe = await this.#gateAsWrite(ctx, target);
-        const resolvedTarget = await this.#resolveHeadingTarget(ctx, safe, headers);
         const url = this.#targetToPath(safe);
+        const format = await this.#wireFormat(ctx, safe, instruction);
+        const resolvedTarget = await this.#resolveHeadingTarget(ctx, safe, instruction, format);
+        const resolved = { ...instruction, target: resolvedTarget };
+        if (format === '1') {
+            await this.#request(ctx, url, {
+                method: 'PATCH',
+                headers: v1PatchHeaders(resolved),
+                body: content,
+            });
+            return resolvedTarget;
+        }
+        const continuation = await this.#listContinuation(ctx, safe, resolved, content);
+        const body = continuation
+            ? v2Instruction(resolved, continuation.content, continuation.within)
+            : v2Instruction(resolved, await this.#sectionRelativeContent(ctx, safe, resolved, content));
         await this.#request(ctx, url, {
             method: 'PATCH',
-            headers: this.#buildPatchHeaders({ ...headers, target: resolvedTarget }),
-            body: content,
+            headers: { 'Content-Type': PATCH_INSTRUCTION_CT, [MARKDOWN_PATCH_VERSION_HEADER]: '2' },
+            body: JSON.stringify(body),
         });
         return resolvedTarget;
     }
@@ -253,12 +310,9 @@ export class ObsidianService {
         }
         const url = this.#targetToPath(target);
         const requestUrl = `${this.#config.baseUrl}${url}`;
-        const res = await this.#fetch(requestUrl, {
+        const res = await this.#send(ctx, requestUrl, {
             method: 'HEAD',
             headers: { Authorization: `Bearer ${this.#config.apiKey}` },
-            dispatcher: this.#dispatcher,
-            ...this.#tlsInit(requestUrl),
-            signal: ctx.signal,
         });
         if (res.status === 404)
             return null;
@@ -316,11 +370,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) });
@@ -344,15 +402,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) {
@@ -492,49 +548,272 @@ export class ObsidianService {
         });
         return (await res.json());
     }
-    /** Raw document-map fetch — bypasses path-policy. Caller must gate. */
+    /**
+     * Raw document-map fetch — bypasses path-policy. Caller must gate. On 2.0 the
+     * nested map is flattened to the 1.x shape this server has always returned.
+     *
+     * Headings are listed in note order. Both formats build their headings from
+     * object keys, so JavaScript lists an integer-like name (`2025`) ahead of its
+     * siblings — the 2.0 tree at every depth, the 1.x map at the top level. Only
+     * then is the note read, and its heading scan (`listHeadingPaths`, the same
+     * parse the map uses) supplies the order.
+     */
     async #rawGetDocumentMap(ctx, target) {
         const url = this.#targetToPath(target);
+        const format = await this.#markdownPatchFormat(ctx);
+        if (format === '1') {
+            const map = await this.#fetchDocumentMap(ctx, url, format);
+            if (!map.headings.some(isIntegerKey))
+                return map;
+            return { ...map, headings: await this.#inNoteOrder(ctx, target, map.headings) };
+        }
+        const raw = await this.#fetchDocumentMap(ctx, url, format);
+        const map = flattenDocumentMap(raw);
+        if (!hasIntegerKey(raw.headings))
+            return map;
+        return { ...map, headings: await this.#inNoteOrder(ctx, target, map.headings) };
+    }
+    /** `paths` in the order the note's own headings run, read from the note. */
+    async #inNoteOrder(ctx, target, paths) {
+        const { content } = await this.#rawGetNoteJson(ctx, target);
+        return inNoteOrder(paths, listHeadingPaths(content));
+    }
+    /** The document map in `format`'s own shape: flat `::`-joined paths for 1.x, the nested tree for 2.0. */
+    async #fetchDocumentMap(ctx, url, format) {
         const res = await this.#request(ctx, url, {
             method: 'GET',
-            headers: {
-                Accept: DOCUMENT_MAP_ACCEPT,
-                [MARKDOWN_PATCH_VERSION_HEADER]: MARKDOWN_PATCH_VERSION,
-            },
+            headers: { Accept: DOCUMENT_MAP_ACCEPT, [MARKDOWN_PATCH_VERSION_HEADER]: format },
             noteRead: true,
         });
         return (await res.json());
     }
+    /**
+     * The markdown-patch format the installed plugin speaks, from `versions.self`
+     * in its `GET /` capability report: 2.0 from Local REST API 5.0 on, 1.x
+     * before. Read once per service. A report that cannot be read fails the
+     * calling write with its classified error — the format is never guessed.
+     *
+     * The report is shared with `#vaultCapabilities`: whichever reads it first
+     * serves the other.
+     */
+    async #markdownPatchFormat(ctx) {
+        this.#patchFormat ??= this.#negotiatePatchFormat(ctx);
+        const pending = this.#patchFormat;
+        try {
+            return await pending;
+        }
+        catch (err) {
+            if (this.#patchFormat === pending)
+                this.#patchFormat = undefined;
+            throw err;
+        }
+    }
+    /**
+     * The format one PATCH goes out in: the plugin's (`#markdownPatchFormat`),
+     * except for two table-row writes that 2.0 cannot express, which go out as
+     * 1.x — plugin 5.x still accepts it.
+     *
+     * - Rows under a heading. 2.0 takes table rows only through a block target
+     *   (a heading write carries its payload in `content`, never `value`); the
+     *   1.x engine appends them to the table that ends the section.
+     * - Rows through an isolated block id — `^id` on its own line after a blank
+     *   line, the way Obsidian places a table's id. 2.0 resolves the id to that
+     *   marker line's own paragraph rather than the table above it, so the write
+     *   fails upstream with "block … is not a table" (markdown-patch 2.0.0,
+     *   `patchTableRows`); the 1.x engine resolves it to the table. Telling the
+     *   shapes apart needs the note, so a block row write on 2.0 reads it once.
+     */
+    async #wireFormat(ctx, target, instruction) {
+        const format = await this.#markdownPatchFormat(ctx);
+        if (format === '1' ||
+            instruction.targetType === 'frontmatter' ||
+            instruction.contentType !== 'json') {
+            return format;
+        }
+        if (instruction.targetType === 'heading')
+            return '1';
+        const { content } = await this.#rawGetNoteJson(ctx, target);
+        return isIsolatedBlockId(content, instruction.target) ? '1' : format;
+    }
+    async #negotiatePatchFormat(ctx) {
+        const status = (await this.#capabilities) ?? (await this.getStatus(ctx));
+        this.#capabilities ??= Promise.resolve(status);
+        return patchFormatFor(status.versions?.self);
+    }
+    /**
+     * The body block a 2.0 heading append or prepend continues, with the content
+     * reduced for a literal splice — or `undefined` for every other write, which
+     * goes out as a plain content write.
+     *
+     * 2.0 separates a plain heading append from the section's last block with a
+     * blank line (a prepend from its first), which turns a tight list loose when
+     * the content is one more item (issue #145). When the content opens with a
+     * list item and the section's own body ends (prepend: opens) with a list,
+     * the write addresses that list `within` the section, and 2.0 splices the
+     * item flush against it, as 1.x placed it. The write stays plain when:
+     *
+     * - a prepend's content ends in anything but a list — its last block meets
+     *   the section's list, and flush against it a paragraph or HTML block would
+     *   take that list in;
+     * - the content carries an ATX heading, which a literal splice would neither
+     *   re-level nor check against the section (`#sectionRelativeContent`);
+     * - an append's section has sub-headings, below which a plain append lands;
+     * - the section already holds the content and duplicates are refused — a
+     *   `within` write searches only the list, the plain one the whole section.
+     *
+     * The note is read only once the content qualifies.
+     */
+    async #listContinuation(ctx, target, instruction, content) {
+        const { operation } = instruction;
+        if (instruction.targetType !== 'heading' || instruction.contentType === 'json')
+            return;
+        if (operation === 'replace')
+            return;
+        const reduced = canonicalContent(content);
+        const blocks = blockKinds(reduced);
+        if (blocks[0] !== 'list' || (operation === 'prepend' && blocks.at(-1) !== 'list'))
+            return;
+        if (atxHeadingMarkers(reduced).markers.length > 0)
+            return;
+        const { content: note } = await this.#rawGetNoteJson(ctx, target);
+        const body = sectionBody(note, instruction.target);
+        if (!body || (operation === 'append' && body.subsections))
+            return;
+        if ((operation === 'append' ? body.blocks.at(-1) : body.blocks[0]) !== 'list')
+            return;
+        if (!instruction.applyIfContentPreexists && body.content.includes(reduced.trim()))
+            return;
+        return { content: reduced, within: operation === 'append' ? -1 : 0 };
+    }
+    /**
+     * Heading content with its `#` levels rewritten to the section-relative ones
+     * markdown-patch 2.0 reads (see `relativeHeadingLevels`), so the note gets
+     * the levels the caller wrote, as it did under 1.x. The section's level comes
+     * from the note itself, read only when the content carries an ATX heading.
+     * Every other payload passes through as written, and so does content for a
+     * section the note lacks and the write will not create, which the plugin
+     * then reports missing.
+     */
+    async #sectionRelativeContent(ctx, target, instruction, content) {
+        if (instruction.targetType !== 'heading' || instruction.contentType === 'json')
+            return content;
+        const fragment = atxHeadingMarkers(content);
+        if (fragment.markers.length === 0)
+            return content;
+        const { content: note } = await this.#rawGetNoteJson(ctx, target);
+        const level = sectionLevel(note, instruction.target, instruction.createTargetIfMissing === true);
+        if (level === undefined)
+            return content;
+        const relative = relativeHeadingLevels(fragment, level);
+        if (relative.ok)
+            return relative.content;
+        /**
+         * The recovery names the calls that do work, so it is built here: the
+         * parent section and the target's level are only known from this note.
+         */
+        const display = displayPath(this.#targetToPath(target));
+        const parent = instruction.target.split(HEADING_DELIMITER).slice(0, -1).join(HEADING_DELIMITER);
+        const elsewhere = parent
+            ? `Append it to the parent section with obsidian_append_to_note with \`section: '${parent}'\`, or to the end of the note with obsidian_append_to_note without \`section\``
+            : 'Append it to the end of the note with obsidian_append_to_note without `section`';
+        throw validationError(`Heading '${relative.heading}' in the content is level ${relative.level}, so it cannot sit inside section '${instruction.target}' (level ${level}) of ${display}: a section write keeps its content inside the section.`, {
+            path: display,
+            reason: 'heading_outside_section',
+            recovery: {
+                hint: `${elsewhere}; to keep it inside '${instruction.target}', write it at level ${level + 1} or deeper.`,
+            },
+        });
+    }
     /**
      * Resolve a heading PATCH target against the note's document map so a bare
      * 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.
+     *
+     * 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`) wherever the plugin serves one, so the map the
+     * PATCH resolves against is also the one that counts its repeats.
+     */
+    async #resolveHeadingTarget(ctx, target, instruction, format) {
+        if (instruction.targetType !== 'heading')
+            return instruction.target;
+        const { headings, occurrences } = await this.#headingIndex(ctx, target, format);
+        const resolved = instruction.target.includes(HEADING_DELIMITER)
+            ? instruction.target
+            : this.#expandHeadingLeaf(target, instruction.target, headings);
+        const repeats = occurrences.filter((p) => p === resolved);
+        if (repeats.length <= 1)
+            return resolved;
+        const display = displayPath(this.#targetToPath(target));
+        const named = resolved === instruction.target ? `'${resolved}'` : `'${instruction.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).
      *
-     * 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.
+     * On 2.0 both come from the 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 serves only the 1.x array, which
+     * cannot count repeats, so there the note body is fetched and scanned
+     * locally (`listHeadingPaths`), which finds headings with the same `marked`
+     * lexing the map does.
+     *
+     * Both lists run in note order, as `#rawGetDocumentMap` explains, so the
+     * `candidates` an ambiguity error names, and the first one its hint offers,
+     * follow the note.
      */
-    async #resolveHeadingTarget(ctx, target, headers) {
-        if (headers.targetType !== 'heading' || headers.target.includes(HEADING_DELIMITER)) {
-            return headers.target;
+    async #headingIndex(ctx, target, format) {
+        const url = this.#targetToPath(target);
+        if (format === '1') {
+            const map = await this.#fetchDocumentMap(ctx, url, format);
+            const { content } = await this.#rawGetNoteJson(ctx, target);
+            const occurrences = listHeadingPaths(content);
+            return { headings: inNoteOrder(map.headings, occurrences), occurrences };
         }
-        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 map = await this.#fetchDocumentMap(ctx, url, format);
+        const flat = flattenHeadingTree(map.headings);
+        const occurrences = hasIntegerKey(map.headings)
+            ? await this.#inNoteOrder(ctx, target, flat)
+            : flat;
+        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,
@@ -562,34 +841,6 @@ export class ObsidianService {
             }
         }
     }
-    #buildPatchHeaders(p) {
-        const headers = {
-            [MARKDOWN_PATCH_VERSION_HEADER]: MARKDOWN_PATCH_VERSION,
-            Operation: p.operation,
-            'Target-Type': p.targetType,
-            Target: encodeURIComponent(p.target),
-            'Content-Type': p.contentType === 'json' ? 'application/json' : 'text/markdown',
-        };
-        if (p.targetDelimiter)
-            headers['Target-Delimiter'] = p.targetDelimiter;
-        if (p.createTargetIfMissing)
-            headers['Create-Target-If-Missing'] = 'true';
-        /**
-         * Sense inversion: markdown-patch 1.0 (shipped with Local REST API v4.0.0)
-         * renamed `Apply-If-Content-Preexists` to `Reject-If-Content-Preexists`
-         * and flipped the default — patches now apply regardless of duplicates
-         * unless the caller opts into rejection. We keep `applyIfContentPreexists`
-         * on the public schema for caller stability and translate here: a falsy
-         * value (the public default) sends the new Reject header to preserve the
-         * historical idempotent-by-default behavior. Replace operations are
-         * exempt at the plugin layer regardless of this flag.
-         */
-        if (!p.applyIfContentPreexists)
-            headers['Reject-If-Content-Preexists'] = 'true';
-        if (p.trimTargetWhitespace)
-            headers['Trim-Target-Whitespace'] = 'true';
-        return headers;
-    }
     /**
      * The TLS relaxation for one request, scoped to that request.
      *
@@ -616,6 +867,34 @@ export class ObsidianService {
             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 = {
@@ -623,13 +902,10 @@ 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,
-                ...this.#tlsInit(url),
-                signal: ctx.signal,
             });
             if (!res.ok) {
                 await this.#throwForStatus(res, pathAndQuery, ctx, {
@@ -728,6 +1004,8 @@ export class ObsidianService {
      * The cache never expires, and does not need to: it is read only to word an
      * error on a call that already failed. Installing the missing extension
      * mid-session makes the route resolve, so no 404 arrives to be classified.
+     * A report the markdown-patch negotiation already read (`#markdownPatchFormat`)
+     * seeds it, so the two share one `GET /`.
      */
     async #vaultCapabilities(ctx) {
         this.#capabilities ??= this.#probeCapabilities(ctx);
@@ -759,10 +1037,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
@@ -804,15 +1084,26 @@ export class ObsidianService {
         const upstreamMsg = typeof body?.message === 'string' ? body.message : text.trim();
         const cause = new UpstreamErrorText(upstreamMsg, opts.requestedUrl);
         const data = (reason) => ({
-            path: display,
+            ...callerIdentifier(path),
             ...(reason !== undefined ? { reason, ...ctx.recoveryFor(reason) } : {}),
         });
+        const contentPreexists = () => validationError(`The supplied content already appears at the target in ${display}. Pass \`applyIfContentPreexists: true\` to force-apply, or change the content.`, data('content_preexists'), { cause });
+        const sectionTargetMissing = () => validationError(`Section target not found in ${display}. Use \`obsidian_get_note\` with \`format: "document-map"\` to list available headings, blocks, and frontmatter fields, then retry with one of those locators.`, data('section_target_missing'), { cause });
         switch (res.status) {
             case 401:
                 throw unauthorized('Obsidian Local REST API rejected the API key. Verify OBSIDIAN_API_KEY matches the value in Obsidian → Settings → Local REST API.', data(), { cause });
             case 403:
                 throw forbidden('Obsidian Local REST API forbids this request. Check the plugin permissions.', data(), { cause });
             case 404: {
+                /**
+                 * A markdown-patch 2.0 PATCH whose section is not in the note answers
+                 * 404 like a missing note, told apart only by the engine's wording —
+                 * as does a `within` write whose body block the note no longer has.
+                 * The 1.x format reports the same miss as a 400 (below).
+                 */
+                if (/\bcould not resolve (?:heading|block|frontmatter) target\b|`within` index -?\d+ is out of range\b/i.test(upstreamMsg)) {
+                    throw sectionTargetMissing();
+                }
                 if (path.startsWith('/active/')) {
                     throw notFound('No file is currently active in Obsidian — open a file in the app first.', data('no_active_file'), { cause });
                 }
@@ -874,16 +1165,24 @@ export class ObsidianService {
                 // Content-preexists is a more specific case nested inside the broader
                 // "could not be applied" family — branch on it first so retries with
                 // identical content surface the right reason and recovery (toggle
-                // `applyIfContentPreexists`) instead of misleading section-miss copy.
+                // `applyIfContentPreexists`) instead of the general patch-rejection copy.
                 if (/content-already-preexists-in-target/i.test(upstreamMsg)) {
-                    throw validationError(`The supplied content already appears at the target in ${display}. Pass \`applyIfContentPreexists: true\` to force-apply, or change the content.`, data('content_preexists'), { cause });
+                    throw contentPreexists();
                 }
-                // The Local REST API returns a "could not be applied to the target
-                // content" / "invalid-target" message when a PATCH names a section that
-                // doesn't exist. Translate to actionable guidance.
-                const isTargetMiss = /\bcould not be applied\b|\binvalid-target\b/i.test(upstreamMsg);
-                if (isTargetMiss) {
-                    throw validationError(`Section target not found in ${display}. Use \`obsidian_get_note\` with \`format: "document-map"\` to list available headings, blocks, and frontmatter fields, then retry with one of those locators.`, data('section_target_missing'), { cause });
+                // The 1.x engine names a section the note lacks with the `invalid-target`
+                // reason token; 2.0 answers the same miss with a 404 (above).
+                if (/\binvalid-target\b/i.test(upstreamMsg)) {
+                    throw sectionTargetMissing();
+                }
+                /**
+                 * Every other patch refusal: the content does not fit a target that
+                 * exists. Each shape gets this file's own sentence, picked from the 1.x
+                 * reason token or the 2.0 engine's wording; the upstream text itself is
+                 * read only to choose, per the containment invariant above.
+                 */
+                const rejection = patchRejection(upstreamMsg, body?.errorCode);
+                if (rejection !== undefined) {
+                    throw validationError(`The Local REST API could not apply the patch to ${display}${rejection ? `: ${rejection}` : ''}.`, data('patch_rejected'), { cause });
                 }
                 // Periodic Notes plugin returns 400 with "Specified period is not enabled"
                 // when the requested period (daily/weekly/monthly/...) is disabled in the
@@ -895,6 +1194,10 @@ export class ObsidianService {
                 throw validationError(`Obsidian Local REST API rejected the request to ${display} as malformed (HTTP 400).`, data(), { cause });
             }
             default: {
+                // markdown-patch 2.0 refuses duplicate content with a 409; 1.x with the 400 above.
+                if (res.status === 409 && /\balready contains the content\b/i.test(upstreamMsg)) {
+                    throw contentPreexists();
+                }
                 /**
                  * Unhandled 4xx and all 5xx. `httpStatusToErrorCode` supplies the same
                  * canonical mapping `httpErrorFromResponse` would (the whole 5xx range
@@ -967,41 +1270,168 @@ export function encodeVaultPath(path) {
     return segments.map((seg) => encodeURIComponent(seg)).join('/');
 }
 /**
- * Locate the match span inside the `context` window the upstream ships with it.
+ * 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.
+ *
+ * `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.
  *
- * `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.
+ * 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 and the URL it answered, carried as the `cause` of
@@ -1113,10 +1543,103 @@ function atLeastVersion(version, floor) {
 function periodOf(urlPath) {
     return /^\/periodic\/(daily|weekly|monthly|quarterly|yearly)\//.exec(urlPath)?.[1] ?? 'periodic';
 }
+/**
+ * Why the plugin refused a patch, in this file's words: `''` for a refusal it
+ * cannot place more precisely, `undefined` when the response is not a patch
+ * refusal at all. A refusal is the plugin's `PatchFailed` (40080, both
+ * formats) or 2.0's `InvalidPatchInstruction` (40081), recognized by code or by
+ * `PatchFailed`'s fixed wording. The detail is chosen from the 1.x engine's
+ * reason token or the 2.0 engine's message; neither is ever returned.
+ */
+function patchRejection(upstreamMsg, errorCode) {
+    const refused = errorCode === 40080 || errorCode === 40081 || /\bcould not be applied\b/i.test(upstreamMsg);
+    if (!refused)
+        return;
+    if (/\bis not a table\b/i.test(upstreamMsg)) {
+        return 'the target block is not a table, so it cannot take table rows';
+    }
+    /**
+     * The 1.x engine reports a row whose cell count does not match the table
+     * under this same token — its table writer rethrows every failure as "not a
+     * table" — so the sentence names both.
+     */
+    if (/content-type-invalid-for-target/i.test(upstreamMsg)) {
+        return "the target block is not a table, or a row's cell count does not match the table's column count";
+    }
+    if (/table-content-incorrect-column-count|\bcell\(s\);.*\bcolumn\(s\)/i.test(upstreamMsg)) {
+        return "a row's cell count does not match the table's column count";
+    }
+    if (/content-not-mergeable|\bnot mergeable\b|\bcannot be merged\b/i.test(upstreamMsg)) {
+        return "the value cannot be merged with the field's current value — append and prepend need two lists, two objects, or two strings";
+    }
+    if (errorCode === 40081 || /\bcontent-type-invalid\b/i.test(upstreamMsg)) {
+        return 'the content does not have the shape this target takes';
+    }
+    return '';
+}
 /** The request path with its query string dropped — the route alone. */
 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