obsidian-mcp-server 3.7.2 → 3.9.0

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

@@ -4,22 +4,69 @@
  * `target` discriminator, and classifies errors for the framework.
  * @module services/obsidian/obsidian-service
  */
-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 { configurationError, conflict, forbidden, JsonRpcErrorCode, McpError, notFound, serviceUnavailable, timeout, unauthorized, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { createPacer, httpStatusToErrorCode, withRetry, } from '@cyanheads/mcp-ts-core/utils';
+import { Agent, Response, fetch as undiciFetch } from 'undici';
 import { getServerConfig } from '../../config/server-config.js';
-import { assertTreeDepth, createJsonLogicEvaluation, readsContent } from './jsonlogic-evaluator.js';
+import { assertNoLinkFields, assertTreeDepth, createJsonLogicEvaluation, readsContent, } from './jsonlogic-evaluator.js';
 import { canonicalContent, flattenDocumentMap, flattenHeadingTree, hasIntegerKey, inNoteOrder, isIntegerKey, patchFormatFor, relativeHeadingLevels, v1HeadingBody, v1PatchHeaders, v2Instruction, } from './patch-instruction.js';
-import { PathPolicy } from './path-policy.js';
-import { atxHeadingMarkers, blockKinds, isIsolatedBlockId, listHeadingPaths, sectionBody, sectionLevel, } from './section-extractor.js';
+import { caseFoldedPattern, PathPolicy } from './path-policy.js';
+import { atxHeadingMarkers, blockKinds, deepestAncestor, droppedDefinitionInReach, isIsolatedBlockId, listHeadingPaths, sectionBody, sectionLevel, } from './section-extractor.js';
+import { isHighSurrogate, isLowSurrogate, SimpleSearch, simpleSearchTokens, } from './simple-search.js';
 /**
- * Most note-body bytes (by `stat.size`) a scoped JSONLogic search fetches and
- * evaluates at once. Each batch costs one upstream search, during which the
- * plugin reads every vault note's body, since the body-fetch tree names
- * `content`; so this trades those vault-wide reads against how much of the
- * readable vault sits in memory.
+ * Most note-body bytes (by `stat.size`) a scoped JSONLogic search holds and
+ * evaluates at once, so a broad scope never holds every readable body. Each
+ * body is its own `GET /vault/{path}`, so the batch size sets memory, not the
+ * number of upstream reads.
  */
 const CONTENT_BATCH_BYTES = 32 * 1024 * 1024;
+/**
+ * Most note-body reads in flight at once, across every search the service
+ * runs, so concurrent searches share the bound rather than each taking it.
+ * The plugin serves every read from Obsidian's own event loop, so each request
+ * in flight queues there; 32 keeps a whole-vault read well inside
+ * {@link SCOPED_SEARCH_DEADLINE_MS} without queuing more than that.
+ */
+const BODY_READ_CONCURRENCY = 32;
+/**
+ * Wall-clock ceiling on one scoped text or JSONLogic search: its upstream
+ * search, every body read with its retries, and the matching or evaluation.
+ * One deadline for the whole search, not one per request, so a search over a
+ * broad scope answers or fails inside the 60 s an MCP client waits for a
+ * response by default.
+ */
+const SCOPED_SEARCH_DEADLINE_MS = 45_000;
+/**
+ * Most characters the plugin's `/search/simple/` response may take for the
+ * hits of a scoped text search: V8's longest string (2^29 − 24 on 64-bit),
+ * where the plugin's `res.json` fails serializing it. `SimpleSearch` counts
+ * that response as the plugin writes it, each match's offsets, escaped window,
+ * and framing with every hit's filename and score, so a scoped search fails
+ * with `context_length_too_large` where the plugin would fail over the
+ * readable notes alone, and never holds more matches than such a response.
+ */
+const SCOPED_TEXT_RESPONSE_CHARS = 2 ** 29 - 24;
+/**
+ * Run a scoped search under {@link SCOPED_SEARCH_DEADLINE_MS}: `run` gets a
+ * signal that aborts with `ctx.signal` or at the deadline, and a failure
+ * caused by the deadline alone is replaced by `tooCostly(cause)`.
+ */
+async function withScopedDeadline(ctx, tooCostly, run) {
+    // A timer rather than `AbortSignal.timeout`, which can fail on a realm mismatch under Bun's stdio transport.
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new DOMException('Scoped search deadline', 'TimeoutError')), SCOPED_SEARCH_DEADLINE_MS);
+    try {
+        return await run(AbortSignal.any([ctx.signal, deadline.signal]));
+    }
+    catch (err) {
+        if (!deadline.signal.aborted || ctx.signal.aborted)
+            throw err;
+        throw tooCostly(err);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Split `notes`, in order, into runs whose bodies total at most {@link CONTENT_BATCH_BYTES}; a larger note gets a run of its own. */
 function contentBatches(notes) {
     const batches = [];
@@ -39,16 +86,24 @@ function contentBatches(notes) {
     return batches;
 }
 /**
- * How long a stored scoped JSONLogic walk outlives its last read. A scoped
- * evaluation reads every readable note, so a walk's later pages are served
- * from the hit list its first page stored rather than evaluated again.
+ * How long a stored scoped walk outlives its last read. A scoped text or
+ * JSONLogic search reads every readable candidate note, so a walk's later
+ * pages are served from the hit list its first page stored rather than
+ * searched again.
  */
 const WALK_TTL_MS = 5 * 60_000;
-/** Most characters all stored walks hold together, each its tree plus its serialized hits; the least recently read goes first. */
+/**
+ * Most characters all stored walks of both modes hold together, each its key
+ * plus its serialized hits; the least recently read goes first.
+ */
 const WALK_STORE_CHARS = 32 * 1024 * 1024;
-/** Size of a stored walk: its serialized tree plus its serialized hits, counted until it passes `limit`. */
-function walkChars(tree, hits, limit) {
-    let total = tree.length;
+/** True when `walk` was stored by a search in `mode`. */
+function isWalkOf(walk, mode) {
+    return walk?.mode === mode;
+}
+/** Size of a JSONLogic walk: its key plus its serialized hits, counted until it passes `limit`. */
+function walkChars(key, hits, limit) {
+    let total = key.length;
     for (const hit of hits) {
         if (total > limit)
             break;
@@ -56,6 +111,38 @@ function walkChars(tree, hits, limit) {
     }
     return total;
 }
+/**
+ * A text walk's hits as it is stored, with its size (its key plus each hit
+ * serialized), or `undefined` once the size passes `limit`. Each hit is
+ * serialized and parsed back, so a stored context window is a string of its
+ * own: the window `SimpleSearch` cuts is a slice of its note body, and on V8
+ * and JSC alike a slice keeps the whole body reachable, which the character
+ * count would not see. JSONLogic hits need no copy: they arrive from the
+ * evaluation worker as copies already.
+ */
+function storedTextHits(key, hits, limit) {
+    let chars = key.length;
+    const copies = [];
+    for (const hit of hits) {
+        const json = JSON.stringify(hit);
+        chars += json.length;
+        if (chars > limit)
+            return;
+        copies.push(JSON.parse(json));
+    }
+    return { chars, hits: copies };
+}
+/** `hit` with its match locations capped at `cap`. */
+function clipMatches(hit, cap) {
+    if (hit.matches.length <= cap)
+        return hit;
+    return {
+        ...hit,
+        matches: hit.matches.slice(0, cap),
+        truncated: true,
+        totalMatches: hit.matches.length,
+    };
+}
 /** Per-call timeout for the startup probe — covers the 4-tuple TCP handshake + a tiny GET. */
 const OMNISEARCH_PROBE_TIMEOUT_MS = 500;
 /**
@@ -91,6 +178,17 @@ const HEADING_DELIMITER = '::';
  * (duplicate `append`, re-run Obsidian command).
  */
 const RETRY_SAFE_METHODS = new Set(['GET', 'PUT', 'DELETE']);
+/**
+ * Wall-clock budget every Local REST API request one tool or resource call
+ * makes shares: each attempt, each backoff, and each request the call chains
+ * (a write's size reads, a patch's note reads, a folder walk). The budget is
+ * this or `OBSIDIAN_REQUEST_TIMEOUT_MS`, whichever is longer, so a call against
+ * a stalled or slow plugin settles inside the 60 s an MCP client waits by
+ * default, and a timeout an operator raised past it is never undercut.
+ */
+const CALL_DEADLINE_MS = 45_000;
+/** The recovery hint every `obsidian_timeout` carries inline, for the reason `classifyFetchRejection` gives. */
+const TIMEOUT_HINT = `Obsidian may be busy or not responding. Retry a read as it is; a write may have applied before the timeout, so read the note before repeating one. If it keeps timing out, check that Obsidian responds, or raise OBSIDIAN_REQUEST_TIMEOUT_MS (a value above ${CALL_DEADLINE_MS / 1000} s also extends the ${CALL_DEADLINE_MS / 1000} s budget the requests of one call share).`;
 /**
  * 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
@@ -145,13 +243,30 @@ export class ObsidianService {
     #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.
+     * capability report. Holds the in-flight promise, with the call it runs
+     * under, so concurrent writes share one read; a failed read is evicted so
+     * the next write tries again.
      */
     #patchFormat;
-    /** Stored scoped JSONLogic walks by id, least recently read first (`pageJsonLogic`). */
+    /** Stored scoped text and JSONLogic walks by id, least recently read first (`pageText`, `pageJsonLogic`). */
     #walks = new Map();
     #walkChars = 0;
+    /**
+     * The queue every note-body read of a scoped text or JSONLogic search waits
+     * in, so {@link BODY_READ_CONCURRENCY} bounds the reads in flight across
+     * concurrent searches rather than per search.
+     */
+    #bodyReads = createPacer({
+        name: 'obsidian-note-bodies',
+        maxConcurrent: BODY_READ_CONCURRENCY,
+    });
+    /**
+     * When each call's request budget ({@link CALL_DEADLINE_MS}) runs out, as an
+     * epoch time, keyed by the call's `Context` — the one object every handler
+     * hands each service method it calls. Armed by the call's first request; the
+     * entry goes with the context.
+     */
+    #callDeadlines = new WeakMap();
     /**
      * @param config - Validated server config (api key, base URL, TLS, timeouts).
      * @param fetchImpl - Optional fetch override for tests. Defaults to undici's
@@ -165,11 +280,17 @@ export class ObsidianService {
          * 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.
+         *
+         * The dispatcher's own `headersTimeout` / `bodyTimeout` are off (`0`): Bun
+         * ignores both, and on Node they would race the request timer
+         * (`withRequestTimer`), the one clock either runtime honors, with an untyped
+         * error of their own — undici's 300 s defaults included, under a timeout an
+         * operator raised past them.
          */
         this.#dispatcher = new Agent({
             connect: { rejectUnauthorized: config.verifySsl },
-            headersTimeout: config.requestTimeoutMs,
-            bodyTimeout: config.requestTimeoutMs,
+            headersTimeout: 0,
+            bodyTimeout: 0,
         });
         this.#fetch = fetchImpl ?? undiciFetch;
     }
@@ -183,14 +304,16 @@ export class ObsidianService {
     }
     /**
      * 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.
+     * REST API and Omnisearch, after rejecting the note-body reads still queued.
+     * 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() {
+        this.#bodyReads.dispose();
         const dispatcher = this.#dispatcher;
         await dispatcher.close?.();
     }
@@ -313,14 +436,29 @@ export class ObsidianService {
      * 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.
+     *
+     * A heading write placed by a heading the note has is checked against the
+     * note's link definitions first (`#refuseDroppedDefinition`). Every step
+     * that needs the note's text shares one read of it: the one
+     * `#headingIndex` made, or else one made on first need.
      */
     async patchNote(ctx, target, content, instruction) {
         const safe = await this.#gateAsWrite(ctx, target);
         const url = this.#targetToPath(safe);
         const format = await this.#wireFormat(ctx, safe, instruction);
-        const { target: resolvedTarget, note } = await this.#resolveHeadingTarget(ctx, safe, instruction, format);
+        const { target: resolvedTarget, note, anchored, } = await this.#resolveHeadingTarget(ctx, safe, instruction, format);
         const resolved = { ...instruction, target: resolvedTarget };
+        let read;
+        const readNote = () => {
+            read ??=
+                note === undefined
+                    ? this.#rawGetNoteJson(ctx, safe).then((json) => json.content)
+                    : Promise.resolve(note);
+            return read;
+        };
         if (format === '1') {
+            if (anchored)
+                this.#refuseDroppedDefinition(safe, resolved, await readNote());
             await this.#request(ctx, url, {
                 method: 'PATCH',
                 headers: v1PatchHeaders(resolved),
@@ -330,10 +468,13 @@ export class ObsidianService {
             });
             return resolvedTarget;
         }
-        const continuation = await this.#listContinuation(ctx, safe, resolved, content);
+        const continuation = await this.#listContinuation(resolved, content, readNote);
+        if (anchored) {
+            this.#refuseDroppedDefinition(safe, resolved, await readNote(), continuation?.within);
+        }
         const body = continuation
             ? v2Instruction(resolved, continuation.content, continuation.within)
-            : v2Instruction(resolved, await this.#sectionRelativeContent(ctx, safe, resolved, content));
+            : v2Instruction(resolved, await this.#sectionRelativeContent(safe, resolved, content, readNote));
         await this.#request(ctx, url, {
             method: 'PATCH',
             headers: { 'Content-Type': PATCH_INSTRUCTION_CT, [MARKDOWN_PATCH_VERSION_HEADER]: '2' },
@@ -359,25 +500,18 @@ export class ObsidianService {
      *      coddingtonbear/obsidian-local-rest-api#237). Always prefer delivered
      *      bytes or HEAD over the metadata field.
      *
-     * Bypasses retries (a 404 is the answer, not a transient failure) and
-     * gates readable on path targets before issuing the HEAD.
+     * One attempt, never retried (HEAD is not in `RETRY_SAFE_METHODS`; a 404 is
+     * the answer, not a transient failure), and gates readable on path targets
+     * before issuing the HEAD.
      */
     async tryGetSize(ctx, target) {
         if (target.type === 'path') {
             this.#policy.assertReadable(target.path, target.resolvedFrom);
         }
         const url = this.#targetToPath(target);
-        const requestUrl = `${this.#config.baseUrl}${url}`;
-        const res = await this.#send(ctx, requestUrl, {
-            method: 'HEAD',
-            headers: { Authorization: `Bearer ${this.#config.apiKey}` },
-        });
+        const res = await this.#request(ctx, url, { method: 'HEAD', noteRead: true, missingOk: true });
         if (res.status === 404)
             return null;
-        if (!res.ok) {
-            await this.#throwForStatus(res, url, ctx, { method: 'HEAD', requestedUrl: requestUrl });
-        }
-        this.#assertNotDirectory(res, url);
         return parseContentLength(res, url);
     }
     /**
@@ -400,7 +534,7 @@ export class ObsidianService {
         let url = '/vault/';
         let normalized = '';
         if (dirPath) {
-            normalized = dirPath.replace(/^\/+|\/+$/g, '');
+            normalized = trimSlashes(dirPath);
             if (normalized)
                 url = `/vault/${encodeVaultPath(normalized)}/`;
         }
@@ -423,9 +557,10 @@ export class ObsidianService {
     /**
      * Vault tags with usage counts, hierarchical parents included. Unscoped, the
      * plugin's `/tags/` with its occurrence counts. That payload carries no
-     * per-note attribution, so under OBSIDIAN_READ_PATHS the tags are read from
-     * the readable notes' contexts instead (one upstream search, no bodies), and
-     * each one counts the readable notes carrying it or a tag nested under it.
+     * per-note attribution, so under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS
+     * the tags are read from the readable notes' contexts instead (one upstream
+     * search, no bodies), and each one counts the readable notes carrying it or a
+     * tag nested under it.
      */
     async listTags(ctx) {
         if (this.#policy.restrictsReads) {
@@ -446,13 +581,18 @@ export class ObsidianService {
      * (`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.
+     * The upstream serializes every match in the vault, its context window and
+     * about 150 characters of offsets and framing, into one response, so a
+     * broad query exhausts V8's string capacity, even at a small
+     * `contextLength`, and comes back as an opaque 500 — caught
+     * here and re-thrown typed, the way `searchOmnisearch` re-throws its own
+     * reachability failure. Under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS
+     * that would make the outcome depend on notes outside the scope, so the
+     * search runs here instead (`#searchTextScoped`).
      */
     async searchText(ctx, query, contextLength = 100) {
+        if (this.#policy.restrictsReads)
+            return await this.#searchTextScoped(ctx, query, contextLength);
         const params = new URLSearchParams({ query, contextLength: String(contextLength) });
         let res;
         try {
@@ -467,112 +607,247 @@ export class ObsidianService {
              * and through it the upstream body `#throwForStatus` attached — on the
              * server side for the log record.
              */
-            throw validationError(`The Local REST API ran out of string capacity assembling match contexts for this search (contextLength ${contextLength}). It builds a context window for every matching note before responding, so the ceiling tracks contextLength multiplied by the number of matches rather than either alone.`, {
+            throw validationError(`The Local REST API ran out of string capacity serializing the matches for this search (contextLength ${contextLength}). Each match costs its context window plus about 150 characters of offsets and framing, so the total tracks the number of matches as well as contextLength.`, {
                 reason: 'context_length_too_large',
                 contextLength,
             }, { 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.
+        const tokens = simpleSearchTokens(query);
+        // Upstream's `score` orders the hits but is not a relevance measure — drop
+        // it on the way out so consumers don't mistake it for one. Omnisearch is
+        // the source of real BM25 ranking.
         return raw.map((h) => ({
             filename: h.filename,
-            matches: mergeIntoLocations(h.matches.map((m) => contextRelativeSpan(m, h.filename, contextLength, tokens)), tokens.length, contextLength).map(({ context, match }) => ({ context, match })),
+            matches: mergeIntoLocations(h.matches.map((m) => contextRelativeSpan(m, h.filename, contextLength, tokens)), tokens.length, contextLength),
         }));
     }
+    /**
+     * Text search under a read scope, with no `/search/simple/` request: one
+     * `/search/` guarded by the read scope and, per token, a case-folded
+     * `regexp` on `path` or `content` (`#textCandidates`) names the readable
+     * notes that may hold every token, their bodies are read one GET each
+     * (`#bodyBatches`), and `SimpleSearch` matches them the way the plugin
+     * does, in the plugin's order. `context_length_too_large` then counts the
+     * plugin's response over the readable notes alone, against
+     * `SCOPED_TEXT_RESPONSE_CHARS`. Every request shares `ctx.signal` and one
+     * deadline, `SCOPED_SEARCH_DEADLINE_MS`; past it the search fails with
+     * `text_search_too_costly`.
+     */
+    async #searchTextScoped(ctx, query, contextLength) {
+        const search = new SimpleSearch(query, contextLength, SCOPED_TEXT_RESPONSE_CHARS);
+        await withScopedDeadline(ctx, (cause) => validationError(`The scoped text search ran past ${SCOPED_SEARCH_DEADLINE_MS / 1000} s reading and matching the readable notes.`, { reason: 'text_search_too_costly' }, { cause }), async (signal) => {
+            const notes = await this.#textCandidates(ctx, search.tokens, signal);
+            // With no token every note matches with no span, and no body can change that.
+            if (search.tokens.length === 0)
+                for (const note of notes)
+                    search.add(note.path, '');
+            else {
+                for await (const batch of this.#bodyBatches(ctx, notes, signal)) {
+                    for (const note of batch)
+                        search.add(note.path, note.content);
+                }
+            }
+        });
+        return search.hits().map((h) => ({
+            filename: h.filename,
+            matches: mergeIntoLocations(h.matches.map(({ context, contextStart, match }) => ({
+                context,
+                match: {
+                    start: match.start,
+                    end: match.end,
+                    contextStart,
+                    contextEnd: contextStart + match.end - match.start,
+                },
+                subject: match.source === 'filename' ? 'filename' : 'body',
+            })), search.tokens.length, contextLength),
+        }));
+    }
+    /**
+     * The readable notes that may hold every token of a scoped text search, in
+     * vault order, from one upstream search: the read-scope guard
+     * (`PathPolicy.readScopePattern`) and, per token, a case-folded `regexp`
+     * (`caseFoldedPattern`) on `path` or `content`, the two places the plugin's
+     * search looks. A token with a character the folding cannot express, or a
+     * line break that could span the basename and the body the plugin joins,
+     * sends no `regexp`, so the notes returned always include every readable
+     * match; `filterReadable` decides what is kept. With no `regexp` at all the
+     * tree never names `content`, so the plugin reads no bodies.
+     */
+    async #textCandidates(ctx, tokens, signal) {
+        const clauses = [{ regexp: [this.#policy.readScopePattern(), { var: 'path' }] }];
+        for (const token of tokens) {
+            const pattern = token.includes('\n') ? undefined : caseFoldedPattern(token);
+            if (pattern === undefined)
+                continue;
+            clauses.push({
+                or: [{ regexp: [pattern, { var: 'path' }] }, { regexp: [pattern, { var: 'content' }] }],
+            });
+        }
+        const guard = { if: [{ and: clauses }, { var: 'stat' }, null] };
+        const res = await this.#postJsonLogic(ctx, guard, signal);
+        const hits = (await res.json());
+        return this.#policy
+            .filterReadable(hits)
+            .map(({ filename, result }) => ({ path: filename, stat: result }));
+    }
     /**
      * JSONLogic search. Unscoped, the tree goes to the plugin unchanged. Under
-     * OBSIDIAN_READ_PATHS the plugin would evaluate it against every note in
-     * the vault, so the tree stays here instead: the readable notes' contexts
+     * OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS (`restrictsReads`) the plugin
+     * would evaluate it against every note in the vault, denied ones included,
+     * so the tree stays here instead: the readable notes' contexts
      * are fetched and the tree is evaluated over those alone
      * (`createJsonLogicEvaluation`), the way the plugin evaluates it. No hit,
-     * result, or error then reads a note outside the read scope; which note a
-     * link resolves to is still Obsidian's vault-wide resolution, so `links`,
-     * `backlinks`, and `unresolvedLinks` can change when a note outside the
-     * scope is created or removed.
+     * result, or error then reads a note outside the read scope. The contexts
+     * carry no `links`, `backlinks`, or `unresolvedLinks`, since which note a
+     * link resolves to depends on notes outside the scope; a tree that names
+     * one fails before any request (`assertNoLinkFields`).
      *
      * The plugin hands a tree note bodies only when its JSON holds the string
-     * `"content"` (`readsContent`); such a tree gets them here too, fetched
-     * and evaluated in batches of at most `CONTENT_BATCH_BYTES` so a broad
-     * scope never holds every readable body at once.
+     * `"content"` (`readsContent`); such a tree gets them here too, one read
+     * per readable note, evaluated in batches of at most `CONTENT_BATCH_BYTES`
+     * so a broad scope never holds every readable body at once. Every request
+     * the search makes shares `ctx.signal` and one deadline,
+     * `SCOPED_SEARCH_DEADLINE_MS`; past it the search fails with
+     * `logic_too_costly`.
      */
     async searchJsonLogic(ctx, logic) {
-        if (this.#policy.restrictsReads) {
-            assertTreeDepth(logic);
-            const evaluation = createJsonLogicEvaluation(logic, { signal: ctx.signal });
-            const notes = await this.#readableNoteContexts(ctx);
-            if (!readsContent(logic))
-                return evaluation.evaluate(notes);
-            const hits = [];
-            for (const batch of contentBatches(notes)) {
-                const bodies = await this.#noteBodies(ctx, batch);
-                const withBodies = batch.map((note) => ({ ...note, content: bodies.get(note.path) ?? '' }));
-                hits.push(...(await evaluation.evaluate(withBodies)));
-            }
-            return hits;
+        if (!this.#policy.restrictsReads) {
+            const res = await this.#postJsonLogic(ctx, logic);
+            return (await res.json());
         }
-        const res = await this.#postJsonLogic(ctx, logic);
-        return (await res.json());
+        assertTreeDepth(logic);
+        assertNoLinkFields(logic);
+        return await withScopedDeadline(ctx, (cause) => validationError(`The scoped JSONLogic search ran past ${SCOPED_SEARCH_DEADLINE_MS / 1000} s reading and evaluating the readable notes.`, {
+            reason: 'logic_too_costly',
+            recovery: {
+                hint: 'A tree that names `content` reads the body of every readable note. Test `path`, `tags`, `frontmatter`, or `stat` instead where they can answer, or ask the operator to narrow OBSIDIAN_READ_PATHS or extend OBSIDIAN_DENY_PATHS.',
+            },
+        }, { cause }), async (signal) => {
+            const evaluation = createJsonLogicEvaluation(logic, { signal });
+            try {
+                const notes = await this.#readableNoteContexts(ctx, signal);
+                if (!readsContent(logic))
+                    return await evaluation.evaluate(notes);
+                const hits = [];
+                for await (const batch of this.#bodyBatches(ctx, notes, signal)) {
+                    hits.push(...(await evaluation.evaluate(batch)));
+                }
+                return hits;
+            }
+            finally {
+                await evaluation.close();
+            }
+        });
     }
     /**
-     * A JSONLogic search for a caller paging through its hits `pageSize` at a
-     * time. Unscoped, it is `searchJsonLogic`. Under OBSIDIAN_READ_PATHS a call
-     * without `walk` evaluates fresh and, when the hits run past one page,
-     * stores the full ordered hit list under a new walk id, returned as `walk`;
+     * A JSONLogic search for a caller paging through its hits, whose page this
+     * call serves ends at index `pageEnd`. Unscoped, it is `searchJsonLogic`.
+     * Under a read scope a call without `walk` evaluates fresh and, when the
+     * hits run past `pageEnd`, so a later page will read them, stores the full
+     * ordered hit list under a new walk id, returned as `walk`;
      * a call naming that id with the same tree is served from the stored list
      * without evaluating. The store belongs to this service, whose read scope
      * is fixed at construction, so a list is only read under the scope that
-     * produced it. Anything else — an expired, evicted, or unknown id, or a
-     * different tree — evaluates fresh, and a call cancelled before it answers
-     * stores nothing.
+     * produced it. Anything else — an expired, evicted, or unknown id, a text
+     * walk's id, or a different tree — evaluates fresh, and a call cancelled
+     * before it answers stores nothing.
      */
-    async pageJsonLogic(ctx, logic, walk, pageSize) {
+    async pageJsonLogic(ctx, logic, walk, pageEnd) {
         if (!this.#policy.restrictsReads)
             return { hits: await this.searchJsonLogic(ctx, logic) };
         // Before serializing it: a tree deep enough overflows `JSON.stringify`'s stack under Bun.
         assertTreeDepth(logic);
-        const tree = JSON.stringify(logic);
-        const stored = walk === undefined ? undefined : this.#walks.get(walk);
-        if (walk !== undefined && stored?.tree === tree && stored.expiresAt > Date.now()) {
-            // Re-inserted so the map stays in last-read order.
-            this.#walks.delete(walk);
-            this.#walks.set(walk, { ...stored, expiresAt: Date.now() + WALK_TTL_MS });
-            return { hits: stored.hits, walk };
-        }
+        const key = JSON.stringify(logic);
+        const stored = this.#readWalk(walk, 'jsonlogic', key);
+        if (stored)
+            return { hits: stored.hits, walk: stored.id };
         const hits = await this.searchJsonLogic(ctx, logic);
-        const id = hits.length > pageSize && !ctx.signal.aborted ? this.#storeWalk(tree, hits) : undefined;
+        if (hits.length <= pageEnd || ctx.signal.aborted)
+            return { hits };
+        const id = this.#storeWalk({
+            mode: 'jsonlogic',
+            key,
+            hits,
+            chars: walkChars(key, hits, WALK_STORE_CHARS),
+        });
         return id === undefined ? { hits } : { hits, walk: id };
     }
     /**
-     * Store a walk's hits under a fresh id, first dropping expired walks and,
-     * while the store would pass {@link WALK_STORE_CHARS}, the least recently
-     * read. A walk larger than the whole store is not kept.
+     * A text search for a caller paging through its hits, whose page this call
+     * serves ends at index `pageEnd`: each hit's match locations capped at
+     * `maxMatchesPerHit`, and only the hits whose filename starts with
+     * `pathPrefix` when one is given. Unscoped, every page runs `searchText`.
+     * Under a read scope a call without `walk` searches fresh and, when the
+     * prefixed hits run past `pageEnd`, so a later page will read them, stores
+     * the capped hits, unprefixed, under a new walk id, returned as
+     * `walk`. A call naming that id with the same `query`, `contextLength`, and
+     * `maxMatchesPerHit` is served from the stored hits with no request, its own
+     * `pathPrefix` applied to them; the scope is fixed for this service, so it
+     * is no part of the key. Anything else — an expired, evicted, or unknown
+     * id, a JSONLogic walk's id, or a changed input — searches fresh, and a
+     * call cancelled before it answers stores nothing.
+     */
+    async pageText(ctx, search, walk, pageEnd) {
+        const { contextLength, maxMatchesPerHit, pathPrefix, query } = search;
+        const prefixed = (hits) => pathPrefix ? hits.filter((hit) => hit.filename.startsWith(pathPrefix)) : hits;
+        const searchFresh = async () => (await this.searchText(ctx, query, contextLength)).map((hit) => clipMatches(hit, maxMatchesPerHit));
+        if (!this.#policy.restrictsReads)
+            return { hits: prefixed(await searchFresh()) };
+        const key = JSON.stringify([query, contextLength, maxMatchesPerHit]);
+        const stored = this.#readWalk(walk, 'text', key);
+        if (stored)
+            return { hits: prefixed(stored.hits), walk: stored.id };
+        const hits = await searchFresh();
+        const page = prefixed(hits);
+        if (page.length <= pageEnd || ctx.signal.aborted)
+            return { hits: page };
+        const copies = storedTextHits(key, hits, WALK_STORE_CHARS);
+        const id = copies && this.#storeWalk({ mode: 'text', key, ...copies });
+        return id === undefined ? { hits: page } : { hits: page, walk: id };
+    }
+    /**
+     * The walk `walk` names when it was stored by a search in `mode` under
+     * `key` and has not expired, re-inserted with its lifetime restarted so the
+     * map stays in last-read order; otherwise `undefined`.
+     */
+    #readWalk(walk, mode, key) {
+        const stored = walk === undefined ? undefined : this.#walks.get(walk);
+        if (!isWalkOf(stored, mode) || stored.key !== key || stored.expiresAt <= Date.now())
+            return;
+        this.#walks.delete(stored.id);
+        stored.expiresAt = Date.now() + WALK_TTL_MS;
+        this.#walks.set(stored.id, stored);
+        return stored;
+    }
+    /**
+     * Store a walk under a fresh id, first dropping expired walks and, while the
+     * store would pass {@link WALK_STORE_CHARS}, the least recently read. A walk
+     * larger than the whole store is not kept.
      */
-    #storeWalk(tree, hits) {
-        const chars = walkChars(tree, hits, WALK_STORE_CHARS);
-        if (chars > WALK_STORE_CHARS)
+    #storeWalk(walk) {
+        if (walk.chars > WALK_STORE_CHARS)
             return;
         const now = Date.now();
         // Every walk lives WALK_TTL_MS past its last read, so expired walks lead the last-read order.
         for (const [id, old] of this.#walks) {
-            if (old.expiresAt > now && this.#walkChars + chars <= WALK_STORE_CHARS)
+            if (old.expiresAt > now && this.#walkChars + walk.chars <= WALK_STORE_CHARS)
                 break;
             this.#walks.delete(id);
             this.#walkChars -= old.chars;
         }
         const id = crypto.randomUUID();
-        this.#walks.set(id, { tree, hits, chars, expiresAt: now + WALK_TTL_MS });
-        this.#walkChars += chars;
+        this.#walks.set(id, { ...walk, id, expiresAt: now + WALK_TTL_MS });
+        this.#walkChars += walk.chars;
         return id;
     }
     /** One upstream JSONLogic search: `tree` posted to `/search/`. */
-    #postJsonLogic(ctx, tree) {
+    #postJsonLogic(ctx, tree, signal = ctx.signal) {
         return this.#request(ctx, '/search/', {
             method: 'POST',
             headers: { 'Content-Type': JSONLOGIC_CT },
             body: JSON.stringify(tree),
+            signal,
         });
     }
     /**
@@ -580,14 +855,14 @@ export class ObsidianService {
      * leaves them, in vault order, from one upstream search whose tree is the
      * server's own: a `regexp` guard on the path (`PathPolicy.readScopePattern`)
      * narrows what the plugin returns, and `filterReadable` decides what is
-     * kept. Each context carries only the fields the plugin documents, its link
-     * fields reduced to readable entries.
+     * kept. Each context carries only the fields the plugin documents, less the
+     * link fields (`RawNoteContextHit`).
      */
-    async #readableNoteContexts(ctx) {
+    async #readableNoteContexts(ctx, signal = ctx.signal) {
         const guard = {
             if: [{ regexp: [this.#policy.readScopePattern(), { var: 'path' }] }, { var: '' }, null],
         };
-        const res = await this.#postJsonLogic(ctx, guard);
+        const res = await this.#postJsonLogic(ctx, guard, signal);
         const hits = (await res.json());
         return this.#policy.filterReadable(hits).map(({ filename, result }) => ({
             tags: result.tags,
@@ -595,35 +870,68 @@ export class ObsidianService {
             stat: result.stat,
             path: filename,
             content: result.content,
-            links: result.links && this.#policy.keepReadable(result.links),
-            backlinks: result.backlinks && this.#policy.keepReadable(result.backlinks),
-            unresolvedLinks: result.unresolvedLinks && this.#policy.keepReadable(result.unresolvedLinks),
         }));
     }
     /**
-     * Bodies of `notes`, already-gated contexts, by path, from one upstream
-     * search for exactly those paths. A body for any other path is dropped; an
-     * empty body is absent, as the plugin's search drops a falsy result.
+     * The bodies of `notes` — readable notes, already gated — in their order,
+     * as runs whose `stat.size` totals at most `CONTENT_BATCH_BYTES` (a larger
+     * note gets a run of its own). Each body is one `GET /vault/{path}`, which
+     * reads that file alone, where a JSONLogic search naming `content` would
+     * read every vault note's body. Reads wait in the service's queue, at most
+     * `BODY_READ_CONCURRENCY` in flight. A run is read only when the caller
+     * asks for the next one, so one run is held at a time. A note gone by the
+     * time it is read has an empty body, as the plugin's search gives it; any
+     * other failure stops the run's remaining reads, waits for the ones in
+     * flight to settle, and is thrown. Every request carries `signal`.
      */
-    async #noteBodies(ctx, notes) {
-        const paths = notes.map((note) => note.path);
-        const guard = { if: [{ in: [{ var: 'path' }, paths] }, { var: 'content' }, null] };
-        const res = await this.#postJsonLogic(ctx, guard);
-        const wanted = new Set(paths);
-        const bodies = new Map();
-        for (const hit of (await res.json())) {
-            if (wanted.has(hit.filename))
-                bodies.set(hit.filename, hit.result);
+    async *#bodyBatches(ctx, notes, signal) {
+        for (const run of contentBatches(notes)) {
+            const stop = new AbortController();
+            const reads = AbortSignal.any([signal, stop.signal]);
+            const queue = run.entries();
+            const withBodies = [];
+            let failure;
+            const lane = async () => {
+                while (failure === undefined) {
+                    const next = queue.next();
+                    if (next.done)
+                        return;
+                    const [index, note] = next.value;
+                    try {
+                        const content = await this.#bodyReads.run((granted) => this.#noteBody(ctx, note.path, granted), { signal: reads });
+                        withBodies[index] = { ...note, content };
+                    }
+                    catch (error) {
+                        failure ??= { error };
+                        stop.abort();
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(BODY_READ_CONCURRENCY, run.length) }, lane));
+            if (failure)
+                throw failure.error;
+            yield withBodies;
         }
-        return bodies;
+    }
+    /** One note's body, read raw as UTF-8 the way the plugin's search reads it; `""` once the note is gone. */
+    async #noteBody(ctx, path, signal) {
+        const res = await this.#request(ctx, `/vault/${encodeVaultPath(path)}`, {
+            method: 'GET',
+            headers: { Accept: 'text/markdown' },
+            noteRead: true,
+            missingOk: true,
+            signal,
+        });
+        const body = await res.text();
+        return res.status === 404 ? '' : body;
     }
     /**
      * One-shot startup probe for the Omnisearch plugin's HTTP endpoint. Returns
      * `true` only when the response is `HTTP 200`, declares `application/json`,
      * and the body parses as a JSON array — unrouted paths on the Omnisearch
      * server also return `200` with an empty body, so status alone is
-     * insufficient. The entry point passes the return value into the
-     * `obsidian_search_notes` factory to decide whether to expose the
+     * insufficient. `omnisearchAvailability` calls it, and only when reads are
+     * unscoped, to decide between the `offered` and `unreachable` states of the
      * `omnisearch` mode.
      */
     async probeOmnisearch(signal) {
@@ -652,25 +960,27 @@ export class ObsidianService {
      * Query the Omnisearch HTTP endpoint. Normalizes the response on the way
      * out: decodes HTML entities + `<br>` → `\n` in `excerpt`, renames `path`
      * to `filename`, and drops `vault`. Throws `omnisearch_unreachable`
-     * (ServiceUnavailable) on network failures or non-2xx responses — the
-     * plugin can shut down mid-session (Obsidian quits, plugin disabled), and
-     * the tool needs a distinct signal from the upstream's success cases.
+     * (ServiceUnavailable) on network failures, on a query that outlasts
+     * `OBSIDIAN_REQUEST_TIMEOUT_MS`, and on non-2xx responses — the plugin can
+     * shut down mid-session (Obsidian quits, plugin disabled), and the tool
+     * needs a distinct signal from the upstream's success cases. One attempt,
+     * the body read under the same timer as the fetch.
      */
     async searchOmnisearch(ctx, query) {
         const url = `${this.#omnisearchUrl}/search?q=${encodeURIComponent(query)}`;
         let res;
         try {
-            res = await this.#fetch(url, {
+            res = await withRequestTimer(ctx.signal, this.#config.requestTimeoutMs, async (signal) => await buffered(await this.#fetch(url, {
                 method: 'GET',
                 dispatcher: this.#dispatcher,
                 ...this.#tlsInit(url),
-                signal: ctx.signal,
-            });
+                signal,
+            })), (expiry) => expiry);
         }
         catch (err) {
             if (ctx.signal?.aborted)
                 throw err;
-            throw serviceUnavailable(`Omnisearch unreachable at ${this.#omnisearchUrl}. The plugin may have stopped (Obsidian quit, plugin disabled, or mobile session).`, {
+            throw serviceUnavailable(`Omnisearch did not answer at ${this.#omnisearchUrl}. The plugin may have stopped (Obsidian quit, plugin disabled, or mobile session), or the query took longer than ${this.#config.requestTimeoutMs / 1000} s.`, {
                 reason: 'omnisearch_unreachable',
                 url: this.#omnisearchUrl,
             }, { cause: err });
@@ -791,17 +1101,26 @@ export class ObsidianService {
      *
      * The report is shared with `#vaultCapabilities`: whichever reads it first
      * serves the other.
+     *
+     * Concurrent calls share one in-flight read, which runs under the call that
+     * started it. When that call is cancelled, the read ends for every call
+     * waiting on it, so a waiting call whose own signal is live reads the
+     * report again itself rather than failing with another caller's
+     * cancellation.
      */
     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;
+        for (;;) {
+            this.#patchFormat ??= { owner: ctx, format: this.#negotiatePatchFormat(ctx) };
+            const pending = this.#patchFormat;
+            try {
+                return await pending.format;
+            }
+            catch (err) {
+                if (this.#patchFormat === pending)
+                    this.#patchFormat = undefined;
+                if (pending.owner === ctx || !pending.owner.signal.aborted || ctx.signal.aborted)
+                    throw err;
+            }
         }
     }
     /**
@@ -811,7 +1130,9 @@ export class ObsidianService {
      *
      * - 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.
+     *   1.x engine appends them to a table that opens the section on the line
+     *   right after the heading line, and refuses a section that starts any
+     *   other way, a blank line included.
      * - 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
@@ -857,9 +1178,10 @@ export class ObsidianService {
      * - 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.
+     * The note (`readNote`, the write's shared read) is read only once the
+     * content qualifies.
      */
-    async #listContinuation(ctx, target, instruction, content) {
+    async #listContinuation(instruction, content, readNote) {
         const { operation } = instruction;
         if (instruction.targetType !== 'heading' || instruction.contentType === 'json')
             return;
@@ -871,8 +1193,7 @@ export class ObsidianService {
             return;
         if (atxHeadingMarkers(reduced).markers.length > 0)
             return;
-        const { content: note } = await this.#rawGetNoteJson(ctx, target);
-        const body = sectionBody(note, instruction.target);
+        const body = sectionBody(await readNote(), instruction.target);
         if (!body || (operation === 'append' && body.subsections))
             return;
         if ((operation === 'append' ? body.blocks.at(-1) : body.blocks[0]) !== 'list')
@@ -885,19 +1206,18 @@ export class ObsidianService {
      * 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.
+     * from the note itself (`readNote`, the write's shared read), 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) {
+    async #sectionRelativeContent(target, instruction, content, readNote) {
         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);
+        const level = sectionLevel(await readNote(), instruction.target, instruction.createTargetIfMissing === true);
         if (level === undefined)
             return content;
         const relative = relativeHeadingLevels(fragment, level);
@@ -935,19 +1255,31 @@ export class ObsidianService {
      * 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. On 1.x the
-     * note read for that count comes back as `note`, for `v1HeadingBody`.
+     * PATCH resolves against is also the one that counts its repeats. A note
+     * read for that parse comes back as `note`, for `v1HeadingBody` and the
+     * rest of the write.
+     *
+     * `anchored` is whether the map places the write by a heading the note has:
+     * the resolved heading itself, or, for a write that creates it, an existing
+     * ancestor. The plugin reads those headings' offsets from the note, so
+     * `patchNote` checks the note's link definitions for these writes alone; a
+     * missing heading the write does not create, or creates at the end of the
+     * note with no ancestor, needs no link-definition check.
      */
     async #resolveHeadingTarget(ctx, target, instruction, format) {
         if (instruction.targetType !== 'heading')
-            return { target: instruction.target, note: undefined };
+            return { target: instruction.target, note: undefined, anchored: false };
         const { headings, occurrences, note } = 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 { target: resolved, note };
+        if (repeats.length <= 1) {
+            const anchored = repeats.length === 1 ||
+                (instruction.createTargetIfMissing === true &&
+                    deepestAncestor(occurrences, resolved) !== undefined);
+            return { target: resolved, note, anchored };
+        }
         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.`, {
@@ -975,7 +1307,8 @@ export class ObsidianService {
      *
      * 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.
+     * follow the note. On 2.0 the note read that order takes comes back as
+     * `note` too.
      */
     async #headingIndex(ctx, target, format) {
         const url = this.#targetToPath(target);
@@ -987,10 +1320,36 @@ export class ObsidianService {
         }
         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 };
+        const distinct = (paths) => [...new Set(paths)].filter(Boolean);
+        if (!hasIntegerKey(map.headings))
+            return { headings: distinct(flat), occurrences: flat };
+        const { content } = await this.#rawGetNoteJson(ctx, target);
+        const occurrences = inNoteOrder(flat, listHeadingPaths(content));
+        return { headings: distinct(occurrences), note: content, occurrences };
+    }
+    /**
+     * Refuse a heading write that a link reference definition the plugin's
+     * `marked` drops would misplace (`droppedDefinitionInReach`): both
+     * markdown-patch engines place headings by offsets that fall short below
+     * such a definition, and neither wire format carries a position this
+     * server could correct. `within` is the 2.0 list continuation the write
+     * goes out as, when it does.
+     */
+    #refuseDroppedDefinition(target, instruction, note, within) {
+        const dropped = droppedDefinitionInReach(note, {
+            path: instruction.target,
+            create: instruction.createTargetIfMissing === true,
+            within,
+        });
+        if (!dropped)
+            return;
+        const display = displayPath(this.#targetToPath(target));
+        throw conflict(`Line ${dropped.line} of ${display} defines the link label [${dropped.label}] a second time. The Local REST API's markdown parser drops a repeated definition and misplaces every heading below it, so this write to section '${instruction.target}' would land outside that section.`, {
+            path: display,
+            reason: 'repeated_link_definition',
+            label: dropped.label,
+            line: dropped.line,
+        }, { literals: [`[${dropped.label}]`] });
     }
     /**
      * Expand a bare heading leaf against the note's heading paths. Resolution
@@ -1065,45 +1424,82 @@ export class ObsidianService {
         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.
+     * One attempt at a Local REST API request — what `#request` runs once, or
+     * hands to `withRetry` — with the dispatcher, the scoped TLS relaxation, and
+     * the attempt's signal attached. The body is read here too, into memory
+     * (`buffered`), so the signal that bounds the fetch bounds the transfer: a
+     * body that stalls fails the attempt the way stalled headers do.
      *
-     * 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.
+     * A rejection 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, or a connection dropped mid-body, 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 attempt's signal aborted — `ctx.signal`, a
+     * search's deadline, the retry deadline, or the request timer — since none of
+     * those is a network fault; `#request` tells them apart.
      */
-    async #send(ctx, url, init) {
+    async #send(ctx, url, init, signal = ctx.signal) {
+        let res;
         try {
-            return await this.#fetch(url, {
+            res = await this.#fetch(url, {
                 ...init,
                 dispatcher: this.#dispatcher,
                 ...this.#tlsInit(url),
-                signal: ctx.signal,
+                signal,
             });
         }
         catch (err) {
-            if (ctx.signal?.aborted)
+            if (signal.aborted)
+                throw err;
+            throw classifyFetchRejection(err, 'request') ?? err;
+        }
+        try {
+            return await buffered(res);
+        }
+        catch (err) {
+            if (signal.aborted)
                 throw err;
-            throw classifyFetchRejection(err) ?? err;
+            throw classifyFetchRejection(err, 'body') ?? err;
         }
     }
-    #request(ctx, pathAndQuery, init) {
+    /**
+     * One Local REST API request, status-checked, its body already read: each
+     * attempt (`#send`) runs under a timer of `OBSIDIAN_REQUEST_TIMEOUT_MS`, the
+     * methods in `RETRY_SAFE_METHODS` retry it, and every attempt and backoff
+     * fits in what is left of the call's budget (`#callRemainingMs`). Whichever
+     * clock ends the request — the timer on an attempt, the budget across them,
+     * or a budget already spent before it starts — it fails as `obsidian_timeout`.
+     * A caller's cancellation passes through as thrown, never retried.
+     */
+    async #request(ctx, pathAndQuery, init) {
         const url = `${this.#config.baseUrl}${pathAndQuery}`;
         const headers = {
             ...(init.headers ?? {}),
             Authorization: `Bearer ${this.#config.apiKey}`,
         };
-        const exec = async () => {
-            const res = await this.#send(ctx, url, {
+        const signal = init.signal ?? ctx.signal;
+        const timeoutMs = this.#config.requestTimeoutMs;
+        /**
+         * A scoped search hands its requests a signal of its own carrying the
+         * search's deadline (`withScopedDeadline`): 45 s from the search's start,
+         * which bounds every request it makes. Those leave the call budget alone,
+         * since two clocks ending at the same instant would race, and the budget
+         * winning would relabel the search's own `*_too_costly` as a timeout.
+         */
+        const budgetMs = signal === ctx.signal ? this.#callRemainingMs(ctx) : Number.POSITIVE_INFINITY;
+        if (budgetMs <= 0)
+            throw this.#timeoutError('call');
+        const exec = async ({ signal: attempt, remainingMs, }) => {
+            const boundMs = Math.min(timeoutMs, remainingMs);
+            const res = await withRequestTimer(attempt, boundMs, (timed) => this.#send(ctx, url, {
                 method: init.method,
                 headers,
                 ...(init.body !== undefined ? { body: init.body } : {}),
-            });
+            }, timed), (expiry) => this.#timeoutError(boundMs < timeoutMs ? 'call' : 'request', expiry));
+            if (res.status === 404 && init.missingOk)
+                return res;
             if (!res.ok) {
                 await this.#throwForStatus(res, pathAndQuery, ctx, {
                     method: init.method,
@@ -1120,21 +1516,70 @@ export class ObsidianService {
             return res;
         };
         if (!RETRY_SAFE_METHODS.has(init.method.toUpperCase())) {
-            return exec();
+            return await exec({ signal, remainingMs: budgetMs });
         }
-        return withRetry(exec, {
-            operation: `obsidian.${init.method} ${pathAndQuery}`,
-            context: {
-                requestId: ctx.requestId,
-                timestamp: ctx.timestamp,
-                ...(ctx.tenantId !== undefined ? { tenantId: ctx.tenantId } : {}),
-                ...(ctx.traceId !== undefined ? { traceId: ctx.traceId } : {}),
-                ...(ctx.spanId !== undefined ? { spanId: ctx.spanId } : {}),
-            },
-            baseDelayMs: 200,
-            maxRetries: 3,
-            signal: ctx.signal,
-        });
+        try {
+            return await withRetry(exec, {
+                operation: `obsidian.${init.method} ${pathAndQuery}`,
+                context: {
+                    requestId: ctx.requestId,
+                    timestamp: ctx.timestamp,
+                    ...(ctx.tenantId !== undefined ? { tenantId: ctx.tenantId } : {}),
+                    ...(ctx.traceId !== undefined ? { traceId: ctx.traceId } : {}),
+                    ...(ctx.spanId !== undefined ? { spanId: ctx.spanId } : {}),
+                },
+                baseDelayMs: 200,
+                maxRetries: 3,
+                signal,
+                ...(Number.isFinite(budgetMs) ? { deadlineMs: budgetMs } : {}),
+            });
+        }
+        catch (err) {
+            /**
+             * `withRetry`'s expiry (`retry_deadline_exceeded`) is the call budget
+             * running out mid-attempt or mid-backoff, so it fails as this service's
+             * own `obsidian_timeout`, attempt count kept. The exception is an attempt
+             * that failed some other typed way (an unreachable plugin, a 5xx) with no
+             * time left to retry it: that failure says more than the clock does.
+             */
+            if (!(err instanceof McpError) || err.data?.reason !== 'retry_deadline_exceeded')
+                throw err;
+            const last = err.cause;
+            if (last instanceof McpError && last.data?.reason !== 'obsidian_timeout')
+                throw last;
+            const attempts = err.data.retryAttempts;
+            throw this.#timeoutError('call', err, typeof attempts === 'number' ? attempts : undefined);
+        }
+    }
+    /** The budget one call's requests share: {@link CALL_DEADLINE_MS}, or the request timeout when that is longer. */
+    get #callBudgetMs() {
+        return Math.max(CALL_DEADLINE_MS, this.#config.requestTimeoutMs);
+    }
+    /** What is left of `ctx`'s call budget, in ms, arming it on the call's first request. */
+    #callRemainingMs(ctx) {
+        let deadline = this.#callDeadlines.get(ctx);
+        if (deadline === undefined) {
+            deadline = Date.now() + this.#callBudgetMs;
+            this.#callDeadlines.set(ctx, deadline);
+        }
+        return deadline - Date.now();
+    }
+    /**
+     * `obsidian_timeout`, bounded by the request timer on one attempt
+     * (`request`) or by the budget a call's requests share (`call`). Authored
+     * here with the hint inline, like `obsidian_unreachable`: it reaches every
+     * tool and the resources that declare no `errors[]`, and its fix is the
+     * operator's. The timer's reason and the retry expiry ride as `cause`.
+     */
+    #timeoutError(bound, cause, retryAttempts) {
+        const message = bound === 'request'
+            ? `The Obsidian Local REST API did not respond within ${this.#config.requestTimeoutMs / 1000} s.`
+            : `This call's requests to the Obsidian Local REST API did not finish within its ${this.#callBudgetMs / 1000} s budget.`;
+        return timeout(message, {
+            reason: 'obsidian_timeout',
+            ...(retryAttempts !== undefined ? { retryAttempts } : {}),
+            recovery: { hint: TIMEOUT_HINT },
+        }, cause === undefined ? undefined : { cause });
     }
     /**
      * Reject a `2xx` note read that actually served a folder listing. The Local
@@ -1277,7 +1722,8 @@ export class ObsidianService {
      * Issues #104, #116, #122, and #159.
      */
     async #throwForStatus(res, path, ctx, opts) {
-        const text = await this.#readBodySafe(res);
+        // Read inside the attempt (`#send`), so this is the body already in memory.
+        const text = await res.text();
         const body = parseJsonObject(text);
         const display = displayPath(path);
         /** Classification input and log payload only — never a wire value. */
@@ -1421,9 +1867,11 @@ export class ObsidianService {
                  * Unhandled 4xx and all 5xx. `httpStatusToErrorCode` supplies the same
                  * canonical mapping `httpErrorFromResponse` would (the whole 5xx range
                  * except 504 → ServiceUnavailable, 504 → Timeout) without that
-                 * helper's response-derived extras: it builds its message from the
-                 * upstream's reason phrase and mirrors the body onto
-                 * `data.body`/`data.responseBody`, which is the #104 leak.
+                 * helper's response-derived extras: its message ends in the upstream's
+                 * reason phrase and `data.statusText` repeats it, upstream-authored
+                 * text the containment invariant above keeps off the wire. The body
+                 * it captures stays server-side by default, but this method has read
+                 * the body already to classify it, and keeps it on `cause`.
                  *
                  * Two `data` fields are re-attached by hand because both steer
                  * `withRetry` and neither carries vault content:
@@ -1445,14 +1893,6 @@ export class ObsidianService {
             }
         }
     }
-    async #readBodySafe(res) {
-        try {
-            return await res.text();
-        }
-        catch {
-            return '';
-        }
-    }
 }
 /**
  * Count, per tag, the notes carrying it or a tag nested under it. Each note's
@@ -1478,14 +1918,29 @@ function countTagsPerNote(notes) {
     }
     return Array.from(counts, ([name, count]) => ({ name, count }));
 }
+/**
+ * `path` less its leading and trailing `/` runs, as `/^\/+|\/+$/g` leaves it,
+ * found by scanning in from each end: the regex retries at every `/` of a run
+ * inside the path, in time quadratic in the run.
+ */
+export function trimSlashes(path) {
+    let start = 0;
+    let end = path.length;
+    while (start < end && path[start] === '/')
+        start++;
+    while (end > start && path[end - 1] === '/')
+        end--;
+    return path.slice(start, end);
+}
 /**
  * Encode a vault-relative path for the URL. Splits on `/` and `\` (so
  * Windows-style separators are honored), URL-encodes each segment, and
  * rejoins with `/` since the Local REST API plugin expects forward slashes.
  *
  * Rejects `.` and `..` segments here rather than relying on the upstream Local
- * REST API plugin to normalize them — `PathPolicy` short-circuits to "allow"
- * when `OBSIDIAN_READ_PATHS` is unset, and `..` is unreserved per RFC 3986 so
+ * REST API plugin to normalize them — with `OBSIDIAN_READ_PATHS` unset,
+ * `PathPolicy` allows every path no deny prefix covers, and `..` is
+ * unreserved per RFC 3986 so
  * `encodeURIComponent` leaves it intact. This is the single chokepoint before
  * URL construction, so guard vault escape here. Backslash is treated as a
  * separator so `..\..\etc` traverses identically to `../../etc` and can't
@@ -1512,15 +1967,6 @@ export function encodeVaultPath(path) {
     }
     return segments.map((seg) => encodeURIComponent(seg)).join('/');
 }
-/**
- * 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.
@@ -1600,9 +2046,10 @@ function bodyWindowOffset(m, contextLength, reproduces) {
     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.
+ * Merge a hit's spans into the match locations `TextSearchHit` carries.
+ * `prepareSimpleSearch` coalesces only token occurrences that overlap or
+ * 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:
@@ -1624,7 +2071,7 @@ function bodyWindowOffset(m, contextLength, reproduces) {
  */
 function mergeIntoLocations(spans, distinctTokens, contextLength) {
     if (distinctTokens < 2)
-        return spans;
+        return spans.map(({ context, match }) => ({ context, match }));
     const locations = [];
     let current;
     for (const span of spans) {
@@ -1643,7 +2090,7 @@ function mergeIntoLocations(spans, distinctTokens, contextLength) {
     }
     if (current)
         locations.push(current.location);
-    return locations;
+    return locations.map(({ context, match }) => ({ context, match }));
 }
 function matchedText(span) {
     return span.context.slice(span.match.contextStart, span.match.contextEnd).toLowerCase();
@@ -1843,23 +2290,26 @@ function callerIdentifier(urlPath) {
     return {};
 }
 /**
- * Classify a rejected `fetch` — one that produced no response at all — or
- * return `undefined` to leave it as thrown.
+ * Classify a rejected `fetch` (`phase: 'request'`, no response at all) or a
+ * rejected body read after the headers arrived (`phase: 'body'`), 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.
+ * fetch failed` (or `terminated`, mid-body). 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. A connection that fails mid-body
+ * is the same `obsidian_unreachable`, worded for a plugin that answered and
+ * then went away rather than one never reached.
  *
  * 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 the framework's contract fill to resolve against.
  */
-function classifyFetchRejection(err) {
+function classifyFetchRejection(err, phase) {
     const codes = [err, err instanceof Error ? err.cause : undefined].flatMap((e) => {
         const code = e?.code;
         return typeof code === 'string' ? [code] : [];
@@ -1874,15 +2324,64 @@ function classifyFetchRejection(err) {
         }, { 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 phase === 'request'
+            ? 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 })
+            : serviceUnavailable('The Obsidian Local REST API closed the connection before its response finished.', {
+                reason: 'obsidian_unreachable',
+                recovery: {
+                    hint: 'Obsidian may have quit, or reloaded the Local REST API plugin, while answering. Confirm it is running with the plugin enabled; a write it was answering may already have applied, so read the note before repeating one.',
+                },
+            }, { cause: err });
     }
     return;
 }
+/**
+ * Run one request attempt — its fetch and its body read — under a timer of
+ * `timeoutMs` joined to `signal`. The timer aborts with a reason held here,
+ * and both runtimes reject the pending fetch or body read with that very
+ * instance, so its expiry is told from every other abort by identity, never
+ * by the `TimeoutError` name a caller's cancellation or a scoped search's
+ * deadline can carry too: `onExpiry` replaces only that rejection. The timer
+ * is cleared however the attempt ends. A timer rather than
+ * `AbortSignal.timeout`, for the reason `withScopedDeadline` gives.
+ */
+async function withRequestTimer(signal, timeoutMs, run, onExpiry) {
+    const timer = new AbortController();
+    const expiry = new DOMException(`Request timer of ${timeoutMs} ms expired`, 'TimeoutError');
+    const id = setTimeout(() => timer.abort(expiry), timeoutMs);
+    try {
+        return await run(AbortSignal.any([signal, timer.signal]));
+    }
+    catch (err) {
+        throw err === expiry ? onExpiry(expiry) : err;
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+/**
+ * `res` with its body read into memory, as an equivalent response a caller
+ * reads with no I/O left. Called inside the attempt, so the signal that bounds
+ * the fetch bounds the transfer too: the request timer, a caller's
+ * cancellation, and a dropped connection all land while the attempt can still
+ * classify and retry them, rather than in a caller's `res.json()` afterwards.
+ * Parsing stays with the caller, outside the retry loop, since a body that
+ * does not parse reads the same on every attempt.
+ */
+async function buffered(res) {
+    const bytes = await res.arrayBuffer();
+    // A null-body status (204, 304) refuses any body, an empty one included.
+    return new Response(bytes.byteLength > 0 ? bytes : null, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers,
+    });
+}
 /**
  * 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
@@ -1932,12 +2431,13 @@ function parseContentLength(res, url) {
 /**
  * Resolve the Omnisearch URL. Override wins. Otherwise: take the host from
  * `OBSIDIAN_BASE_URL`, force `http:` (Omnisearch is HTTP-only), swap port
- * `27123/27124` → `51361`. `127.0.0.1` is mapped to `localhost` since
- * Omnisearch's current Node listener binds IPv4 only but the platform's
- * loopback resolver is flexible — `localhost` insulates us if a future
- * build switches binding. Falls back to `http://localhost:51361` on any
- * URL parse failure (config validation catches malformed `baseUrl`, so this
- * is belt-and-suspenders).
+ * `27123/27124` → `51361`. `127.0.0.1` is mapped to `localhost` because
+ * Omnisearch (1.31.0) listens on host `localhost` by default, which binds the
+ * one address `localhost` resolves to first — `::1` on a macOS host, so a
+ * literal `127.0.0.1` would be refused there — and requesting `localhost`
+ * reaches whichever address that is. Falls back to `http://localhost:51361`
+ * on any URL parse failure (config validation catches malformed `baseUrl`, so
+ * this is belt-and-suspenders).
  */
 function deriveOmnisearchUrl(config) {
     if (config.omnisearchUrl)
@@ -1964,8 +2464,8 @@ function normalizeOmnisearchHit(raw) {
 /**
  * Normalize Omnisearch's excerpt HTML: `<br>` → `\n`, decode the entities
  * the upstream actually emits (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#039;`,
- * `&apos;`, plus numeric `&#NNN;` / `&#xNN;`). `<mark>` tags are preserved —
- * they highlight the match span and are interpretable as emphasis.
+ * `&apos;`, plus numeric `&#NNN;` / `&#xNN;`). Omnisearch's HTTP API adds no
+ * highlight markup; it marks matches only in its own UI.
  */
 function cleanExcerpt(excerpt) {
     return excerpt