openwriter 0.14.0 → 0.15.0

package/dist/server/mcp.js

@@ -10,19 +10,20 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync } from './helpers.js';
-import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument, invalidateDocCache, isAutoAcceptActive, } from './state.js';
+import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, } from './state.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, searchDocuments } from './documents.js';
 import { extractForwardLinks } from './backlinks.js';
-import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastMarksChanged } from './ws.js';
-import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces } from './workspaces.js';
+import { logger, generateRequestId, withRequestId } from './logger.js';
+import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
+import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
 import { findDocNode } from './workspace-tree.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent, mergeParagraphsToHardBreaks } from './compact.js';
 import matter from 'gray-matter';
 import { getUpdateInfo } from './update-check.js';
-import { listVersions, forceSnapshot, restoreVersion } from './versions.js';
+import { listVersions, forceSnapshot, getVersionContent } from './versions.js';
 import { markdownToTiptap, tiptapToMarkdown } from './markdown.js';
-import { getMarks, getMarkCount, getGlobalMarkSummary, resolveMarks } from './marks.js';
+import { getComments, getCommentCount, getGlobalCommentSummary, resolveComments } from './comments.js';
 import { readTasks, addTask, updateTask, removeTask } from './tasks.js';
 /** Map a content type string to its frontmatter metadata object. */
 function resolveTypeMeta(type, url) {
@@ -113,6 +114,75 @@ function resolveDocTarget(docId) {
         lastModified: statSync(filePath).mtime,
     };
 }
+/** Human-friendly relative time for ISO timestamps. */
+function relativeTime(iso) {
+    const then = new Date(iso).getTime();
+    if (!isFinite(then))
+        return '';
+    const diff = Date.now() - then;
+    if (diff < 0)
+        return 'just now';
+    const sec = Math.round(diff / 1000);
+    if (sec < 60)
+        return 'just now';
+    const min = Math.round(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.round(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.round(hr / 24);
+    if (day < 14)
+        return `${day}d ago`;
+    const wk = Math.round(day / 7);
+    if (wk < 8)
+        return `${wk}w ago`;
+    const mo = Math.round(day / 30);
+    if (mo < 12)
+        return `${mo}mo ago`;
+    return `${Math.round(day / 365)}y ago`;
+}
+/** Apply a scope filter to the comments index. Returns the matching comments
+ *  grouped by file plus a human-readable label for the scope. */
+function gatherComments(filename, scope) {
+    const effectiveScope = scope ?? (filename ? 'workspace' : 'all');
+    if (effectiveScope === 'document' && filename) {
+        return { byFile: getComments(filename), scopeLabel: `document "${filename}"` };
+    }
+    if (effectiveScope === 'workspace' && filename) {
+        const containing = findWorkspacesContainingDoc(filename);
+        if (containing.length === 0) {
+            // Doc isn't filed in any workspace — fall back to single-doc scope.
+            return { byFile: getComments(filename), scopeLabel: `document "${filename}" (not in any workspace)` };
+        }
+        const ws = containing[0];
+        const filesInWs = collectFilesInWorkspace(ws.filename);
+        const byFile = {};
+        for (const f of filesInWs) {
+            const docComments = getComments(f);
+            if (docComments[f] && docComments[f].length > 0)
+                byFile[f] = docComments[f];
+        }
+        return { byFile, scopeLabel: `workspace "${ws.title}" (${filesInWs.length} docs)` };
+    }
+    return { byFile: getComments(), scopeLabel: 'all documents' };
+}
+function formatCommentsOutput({ byFile, scopeLabel }) {
+    const entries = Object.entries(byFile);
+    if (entries.length === 0)
+        return `No comments found in ${scopeLabel}.`;
+    const total = entries.reduce((sum, [, list]) => sum + list.length, 0);
+    const lines = [`Comments in ${scopeLabel} — ${total} total:`];
+    for (const [file, comments] of entries) {
+        lines.push(`\n${file}:`);
+        for (const c of comments) {
+            const notePart = c.note ? ` — "${c.note}"` : '';
+            const age = c.createdAt ? `  [${relativeTime(c.createdAt)}]` : '';
+            lines.push(`  [${c.id}] "${c.text}"${notePart}${age}  (node:${c.nodeId})`);
+        }
+    }
+    return lines.join('\n');
+}
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
@@ -123,15 +193,15 @@ export const TOOL_REGISTRY = [
         handler: async ({ docId }) => {
             const target = resolveDocTarget(docId);
             const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
-            const localCount = getMarkCount(target.filename);
-            const { totalMarks: otherMarks, docCount: otherDocs } = getGlobalMarkSummary(target.filename);
+            const localCount = getCommentCount(target.filename);
+            const { totalComments: otherCount, docCount: otherDocs } = getGlobalCommentSummary(target.filename);
             let hint = '';
             if (localCount > 0)
-                hint += `\n[${localCount} agent mark${localCount !== 1 ? 's' : ''} on this document]`;
-            if (otherMarks > 0)
-                hint += `\n[${otherMarks} agent mark${otherMarks !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
+                hint += `\n[${localCount} comment${localCount !== 1 ? 's' : ''} on this document]`;
+            if (otherCount > 0)
+                hint += `\n[${otherCount} comment${otherCount !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
             if (hint)
-                hint += '\n[call get_agent_marks to review]';
+                hint += '\n[call get_comments to review]';
             return { content: [{ type: 'text', text: compact + hint }] };
         },
     },
@@ -226,6 +296,22 @@ export const TOOL_REGISTRY = [
             // so the agent stops waiting for review when it's on.
             if (isAutoAcceptActive(target.filename, target.metadata))
                 status.autoAccept = true;
+            // External-write drift: only meaningful for the active doc (non-active
+            // docs are read fresh from disk on each access). If the file's on-disk
+            // mtime differs from what we loaded, an external writer modified the
+            // file — the next save would be blocked by the guard. Surface this so
+            // agents can call reload_from_disk before re-attempting a write.
+            // adr: adr/external-write-guard.md
+            if (target.isActive) {
+                const drift = getExternalMtimeDrift();
+                if (drift) {
+                    status.externalWriteDetected = {
+                        diskMtime: new Date(drift.diskMtime).toISOString(),
+                        loadedMtime: new Date(drift.loadedMtime).toISOString(),
+                        note: 'File modified externally. Call reload_from_disk before writing or your changes will be blocked.',
+                    };
+                }
+            }
             const latestVersion = getUpdateInfo();
             const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
             return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -317,8 +403,8 @@ export const TOOL_REGISTRY = [
             try {
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
-                    setAgentLock();
                     const result = createDocument(title, undefined, path);
+                    setAgentLock(result.filename);
                     // Apply type-specific metadata
                     if (content_type) {
                         const typeMeta = resolveTypeMeta(content_type, url);
@@ -418,7 +504,7 @@ export const TOOL_REGISTRY = [
                 // Active target (or no filename): existing flow.
                 // Skip pending tagging when autoAccept is effectively on (doc flag or
                 // inherited from workspace/container) — content commits directly.
-                setAgentLock(); // Block browser doc-updates during population
+                setAgentLock(filename || getActiveFilename()); // Block browser doc-updates during population
                 if (!isAutoAcceptActive(filename || getActiveFilename(), getMetadata())) {
                     markAllNodesAsPending(doc, 'insert');
                 }
@@ -1075,7 +1161,7 @@ export const TOOL_REGISTRY = [
                     }
                     updateDocument(doc);
                     save();
-                    setAgentLock();
+                    setAgentLockActive();
                     broadcastDocumentSwitched(doc, getTitle(), getActiveFilename(), getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, lastNodeId: imgId }) }] };
                 }
@@ -1153,27 +1239,45 @@ export const TOOL_REGISTRY = [
         },
         handler: async ({ docId, timestamp }) => {
             const target = resolveDocTarget(docId);
-            // Safety net: snapshot current state before restoring
+            // Safety checkpoint = the current canonical state. Under the layered
+            // model, disk is already canonical (pending lives in the sidecar
+            // overlay, not in the .md), so forceSnapshot of the current file is
+            // a clean recovery point. The canonical-only-clone special case is
+            // no longer needed.
+            // adr: adr/pending-overlay-model.md
             try {
                 forceSnapshot(target.docId, target.filePath);
             }
             catch { /* best effort */ }
-            const parsed = restoreVersion(target.docId, timestamp);
-            if (!parsed)
+            // Read the target snapshot's content
+            const snapshotMarkdown = getVersionContent(target.docId, timestamp);
+            if (!snapshotMarkdown)
                 return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
+            // Write the snapshot directly to disk — this becomes the new canonical.
+            // The pending overlay sidecar is unchanged; on reload, the matcher
+            // re-pairs nodeIds and pending decorations re-attach where possible.
+            // Pending entries whose anchors disappeared become orphan-inserts.
+            atomicWriteFileSync(target.filePath, snapshotMarkdown);
             if (target.isActive) {
-                updateDocument(parsed.document);
-                save();
-                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
+                // Unified reload pathway — same code path as external-write reload
+                // and explicit reload_from_disk. Re-reads canonical + applies
+                // sidecar overlay + classifies orphans/stale-baseline.
+                const reloaded = reloadActiveDocFromDisk();
+                if (!reloaded)
+                    return { content: [{ type: 'text', text: `Error: Failed to reload after restore.` }] };
+                broadcastDocumentSwitched(reloaded.document, reloaded.title, reloaded.filename);
+                broadcastPendingDocsChanged();
+                const summary = reloaded.orphans.length > 0 || reloaded.staleBaseline.length > 0
+                    ? ` (${reloaded.orphans.length} orphan, ${reloaded.staleBaseline.length} stale-baseline pending)` : '';
+                return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()}${summary}` }] };
             }
             else {
-                // Write restored content to file without switching active doc
-                const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
-                atomicWriteFileSync(target.filePath, markdown);
                 invalidateDocCache(target.filePath);
+                removePendingCacheEntry(target.filename);
                 broadcastDocumentsChanged();
+                broadcastPendingDocsChanged();
+                return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()}` }] };
             }
-            return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()} — "${parsed.title}"` }] };
         },
     },
     {
@@ -1187,12 +1291,19 @@ export const TOOL_REGISTRY = [
             if (!existsSync(target.filePath))
                 return { content: [{ type: 'text', text: `Error: File not found: ${target.filePath}` }] };
             if (target.isActive) {
-                const markdown = readFileSync(target.filePath, 'utf-8');
-                const parsed = markdownToTiptap(markdown);
-                updateDocument(parsed.document);
-                save();
-                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
-                return { content: [{ type: 'text', text: `Reloaded "${parsed.title}" from disk` }] };
+                // Unified reload pathway — same as the fs.watch handler and
+                // restore_version. Re-parses canonical + re-applies the sidecar
+                // overlay (preserves pending changes by nodeId) + classifies any
+                // orphans / stale-baseline entries + restamps loadedMtime.
+                // adr: adr/pending-overlay-model.md · adr: adr/active-doc-watcher.md
+                const reloaded = reloadActiveDocFromDisk();
+                if (!reloaded)
+                    return { content: [{ type: 'text', text: `Error: Failed to reload from disk.` }] };
+                broadcastDocumentSwitched(reloaded.document, reloaded.title, reloaded.filename);
+                broadcastPendingDocsChanged();
+                const summary = reloaded.orphans.length > 0 || reloaded.staleBaseline.length > 0
+                    ? ` (${reloaded.orphans.length} orphan, ${reloaded.staleBaseline.length} stale-baseline pending)` : '';
+                return { content: [{ type: 'text', text: `Reloaded "${reloaded.title}" from disk${summary}` }] };
             }
             else {
                 // Non-active: just invalidate cache so next access re-reads from disk
@@ -1201,47 +1312,67 @@ export const TOOL_REGISTRY = [
             }
         },
     },
+    {
+        name: 'get_comments',
+        description: 'Get inline reader comments left by the user. Users select text in the editor, right-click → Comment, and leave a note for the agent. Returns comments grouped by document with text, note, nodeId, and a relative age. Default scope is "workspace" when docId is provided — comments for every doc in the same project. Pass scope:"document" to narrow to one doc, or scope:"all" to span every document on disk. Call resolve_comments after addressing each comment.',
+        schema: {
+            docId: z.string().optional().describe('Target document by docId (8-char hex). When provided, default scope is "workspace".'),
+            scope: z.enum(['workspace', 'document', 'all']).optional().describe('Filter scope. Default: "workspace" when docId is given, otherwise "all".'),
+        },
+        handler: async ({ docId, scope }) => {
+            const filename = docId ? resolveDocId(docId) : undefined;
+            const resolved = gatherComments(filename, scope);
+            return { content: [{ type: 'text', text: formatCommentsOutput(resolved) }] };
+        },
+    },
+    {
+        name: 'resolve_comments',
+        description: 'Remove comments after addressing the user\'s feedback. Pass the comment IDs from get_comments. Decorations clear in the browser immediately.',
+        schema: {
+            comment_ids: z.array(z.string()).describe('Array of comment IDs to resolve'),
+        },
+        handler: async ({ comment_ids }) => {
+            const resolved = resolveComments(comment_ids);
+            const activeFile = getActiveFilename();
+            broadcastCommentsChanged(activeFile);
+            return {
+                content: [{
+                        type: 'text',
+                        text: resolved.length > 0
+                            ? `Resolved ${resolved.length} comment${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
+                            : 'No matching comments found.',
+                    }],
+            };
+        },
+    },
     {
         name: 'get_agent_marks',
-        description: 'Get inline feedback marks left by the user. Users select text in the editor, right-click → Agent Mark, and leave notes for the agent. Returns marks grouped by document with text, note, and nodeId. Call resolve_agent_marks after addressing each mark.',
+        description: 'DEPRECATED — renamed to get_comments. Use get_comments instead. This alias may be removed in a future release.',
         schema: {
-            docId: z.string().optional().describe('Target document by docId (8-char hex). Omit to get marks across all documents.'),
+            docId: z.string().optional().describe('Target document by docId (8-char hex). Omit to get comments across all documents.'),
         },
         handler: async ({ docId }) => {
             const filename = docId ? resolveDocId(docId) : undefined;
-            const marks = getMarks(filename);
-            const entries = Object.entries(marks);
-            if (entries.length === 0) {
-                return { content: [{ type: 'text', text: 'No agent marks found.' }] };
-            }
-            const lines = [];
-            for (const [file, fileMarks] of entries) {
-                lines.push(`${file}:`);
-                for (const m of fileMarks) {
-                    const notePart = m.note ? ` — "${m.note}"` : '';
-                    lines.push(`  [${m.id}] "${m.text}"${notePart}  (node:${m.nodeId})`);
-                }
-            }
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            const resolved = gatherComments(filename, undefined);
+            return { content: [{ type: 'text', text: formatCommentsOutput(resolved) }] };
         },
     },
     {
         name: 'resolve_agent_marks',
-        description: 'Remove agent marks after addressing the user\'s feedback. Pass the mark IDs from get_agent_marks. Decorations clear in the browser immediately.',
+        description: 'DEPRECATED — renamed to resolve_comments. Use resolve_comments instead. This alias may be removed in a future release.',
         schema: {
-            mark_ids: z.array(z.string()).describe('Array of mark IDs to resolve'),
+            mark_ids: z.array(z.string()).describe('Array of comment IDs to resolve'),
         },
         handler: async ({ mark_ids }) => {
-            const resolved = resolveMarks(mark_ids);
-            // Broadcast to browser so decorations update
+            const resolved = resolveComments(mark_ids);
             const activeFile = getActiveFilename();
-            broadcastMarksChanged(activeFile);
+            broadcastCommentsChanged(activeFile);
             return {
                 content: [{
                         type: 'text',
                         text: resolved.length > 0
-                            ? `Resolved ${resolved.length} mark${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
-                            : 'No matching marks found.',
+                            ? `Resolved ${resolved.length} comment${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
+                            : 'No matching comments found.',
                     }],
             };
         },
@@ -1298,17 +1429,68 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'link_to',
-        description: 'Wrap anchor text in the ACTIVE doc with a doc: link pointing at another doc. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
+        description: 'Wrap anchor text in a source doc with a doc: link pointing at another doc. Operates in place on the block containing the anchor text — never creates a duplicate paragraph. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
         schema: {
-            text: z.string().describe('Anchor text in the active doc to wrap with the link. Exact substring match. First occurrence wins if the text appears multiple times.'),
-            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs).'),
+            text: z.string().describe('Anchor text in the source doc to wrap with the link. Exact substring match. First UNLINKED occurrence wins — calling link_to N times with the same anchor wraps N distinct occurrences, skipping ones already linked to the same target.'),
+            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc containing the anchor text. NOT the active doc — must be explicit so user-driven navigation in the browser can\'t silently change the target.'),
+            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the link points AT.'),
             target_node_id: z.string().optional().describe('Optional 8-char hex nodeId for paragraph-level targeting. When provided, clicking the link scrolls to that paragraph in the target doc.'),
             quote: z.string().optional().describe('Optional text snippet for scroll-anchor fallback when target_node_id has drifted (e.g. paragraph was rewritten).'),
         },
-        handler: async ({ text, target_doc_id, target_node_id, quote }) => {
-            // 1. Locate the block in the active doc that contains the anchor text
-            const doc = getDocument();
+        handler: async ({ text, source_doc_id, target_doc_id, target_node_id, quote }) => {
+            const sourceFilename = resolveDocId(source_doc_id);
+            if (!sourceFilename) {
+                return { content: [{ type: 'text', text: `source_doc_id "${source_doc_id}" not found. Use list_documents to find the right docId.` }] };
+            }
+            // Build the href in canonical doc:DOCID#NODEID?q=quote form so we can also
+            // detect "this text is already wrapped with THIS link" and skip it.
+            let href = `doc:${target_doc_id}`;
+            if (target_node_id)
+                href += `#${target_node_id}`;
+            if (quote)
+                href += `?q=${encodeURIComponent(quote)}`;
+            // Load the source doc — from in-memory state if it's active, from disk
+            // otherwise. Explicit source dispatch prevents the active-doc race where
+            // a user click in the browser silently changes which doc gets edited.
+            const sourceIsActive = sourceFilename === getActiveFilename();
+            let sourceDoc;
+            if (sourceIsActive) {
+                sourceDoc = getDocument();
+            }
+            else {
+                const cached = getCachedDocument(resolveDocPath(sourceFilename));
+                if (cached) {
+                    sourceDoc = cached.document;
+                }
+                else {
+                    try {
+                        const raw = readFileSync(resolveDocPath(sourceFilename), 'utf-8');
+                        sourceDoc = markdownToTiptap(raw).document;
+                    }
+                    catch (err) {
+                        return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}": ${err.message}` }] };
+                    }
+                }
+            }
+            // Locate the first block containing the anchor text WHERE the text is
+            // not already entirely wrapped with a link to the same href. This makes
+            // link_to idempotent and lets repeat calls wrap successive occurrences.
             let sourceNodeId = null;
+            let totalOccurrences = 0;
+            let alreadyLinkedOccurrences = 0;
+            function isTextAlreadyLinked(nodeContent) {
+                // Concatenate text from inline children that have a link mark matching href
+                let linkedText = '';
+                for (const child of nodeContent) {
+                    if (child.type !== 'text' || !child.text)
+                        continue;
+                    const marks = child.marks || [];
+                    const hasMatchingLink = marks.some((m) => m.type === 'link' && m.attrs?.href === href);
+                    if (hasMatchingLink)
+                        linkedText += child.text;
+                }
+                return linkedText.includes(text);
+            }
             function walk(nodes) {
                 if (sourceNodeId)
                     return;
@@ -1318,6 +1500,12 @@ export const TOOL_REGISTRY = [
                     if (Array.isArray(node.content)) {
                         const blockText = node.content.map((c) => c.text || '').join('');
                         if (node.attrs?.id && blockText.includes(text)) {
+                            totalOccurrences++;
+                            if (isTextAlreadyLinked(node.content)) {
+                                alreadyLinkedOccurrences++;
+                                walk(node.content);
+                                continue;
+                            }
                             sourceNodeId = node.attrs.id;
                             return;
                         }
@@ -1325,26 +1513,32 @@ export const TOOL_REGISTRY = [
                     }
                 }
             }
-            walk(doc.content);
+            walk(sourceDoc.content);
             if (!sourceNodeId) {
-                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in the active doc. Use search_docs first to locate the right doc.` }] };
+                if (totalOccurrences > 0 && totalOccurrences === alreadyLinkedOccurrences) {
+                    return { content: [{ type: 'text', text: `Anchor text "${text}" found in source doc but all ${totalOccurrences} occurrence(s) are already linked to ${href}. Nothing to do.` }] };
+                }
+                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in source doc "${source_doc_id}" (${sourceFilename}). Use search_docs or read_pad to verify.` }] };
             }
-            // 2. Build the href in canonical doc:DOCID#NODEID?q=quote form
-            let href = `doc:${target_doc_id}`;
-            if (target_node_id)
-                href += `#${target_node_id}`;
-            if (quote)
-                href += `?q=${encodeURIComponent(quote)}`;
-            // 3. Apply the link mark to the matched substring via the existing text-edit pipeline
-            const result = applyTextEdits(sourceNodeId, [{
-                    find: text,
-                    addMark: { type: 'link', attrs: { href } },
-                }]);
-            if (!result.success) {
-                return { content: [{ type: 'text', text: `Failed to apply link mark: ${result.error}` }] };
+            // Apply the link mark in place. Dispatch by active vs non-active so the
+            // edit always lands in the right doc — never silently in whatever doc
+            // happens to be foregrounded in the browser.
+            const editResult = sourceIsActive
+                ? applyTextEdits(sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }])
+                : applyTextEditsToFile(sourceFilename, sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }]);
+            if (!editResult.success) {
+                return { content: [{ type: 'text', text: `Failed to apply link mark: ${editResult.error}` }] };
             }
-            save(); // triggers writeToDisk → backlinks pipeline auto-updates the target's frontmatter
-            return { content: [{ type: 'text', text: `Linked "${text}" in node ${sourceNodeId} → ${href}. Target doc's backlinks frontmatter will refresh on next save.` }] };
+            if (sourceIsActive)
+                save(); // triggers writeToDisk → backlinks pipeline updates target's frontmatter
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            success: true,
+                            sourceDocId: source_doc_id,
+                            sourceFilename,
+                            nodeId: sourceNodeId,
+                            href,
+                            ...(totalOccurrences > 1 ? { remainingUnlinked: totalOccurrences - alreadyLinkedOccurrences - 1 } : {}),
+                        }) }] };
         },
     },
     {
@@ -1505,8 +1699,26 @@ export async function startMcpServer() {
         name: 'openwriter',
         version: '0.2.0',
     });
+    // Wrap each tool handler in withRequestId so every event logged during
+    // the tool's execution inherits the same request ID. Trace one MCP call
+    // through the system with: jq 'select(.requestId=="mcp-toolname-xxxxxx")'.
+    // adr: adr/logging-system.md
     for (const tool of TOOL_REGISTRY) {
-        server.tool(tool.name, tool.description, tool.schema, tool.handler);
+        const wrappedHandler = async (args) => {
+            const reqId = generateRequestId(`mcp-${tool.name}`);
+            return await withRequestId(reqId, async () => {
+                logger.debug('mcp', 'tool-call', tool.name, { tool: tool.name });
+                try {
+                    const result = await tool.handler(args);
+                    return result;
+                }
+                catch (err) {
+                    logger.error('mcp', 'tool-error', `${tool.name}: ${err.message}`, { tool: tool.name }, err);
+                    throw err;
+                }
+            });
+        };
+        server.tool(tool.name, tool.description, tool.schema, wrappedHandler);
     }
     mcpServerInstance = server;
     const transport = new StdioServerTransport();

package/dist/server/node-blocks.js

@@ -51,6 +51,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
                 inlineMarks: countInlineMarks(node.content || []),
+                id: node.attrs?.id,
             });
         }
         else if (node.type === 'paragraph') {
@@ -62,6 +63,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
                 inlineMarks: countInlineMarks(node.content || []),
+                id: node.attrs?.id,
             });
         }
         else if (node.type === 'bulletList' || node.type === 'orderedList' || node.type === 'taskList') {
@@ -72,6 +74,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: '',
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
             walkNodes(node.content || [], blocks, containerPosition);
         }
@@ -86,6 +89,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: firstParaText,
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
             walkNodes(node.content || [], blocks, itemPosition);
         }
@@ -97,6 +101,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: '',
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
             walkNodes(node.content || [], blocks, bqPosition);
         }
@@ -109,6 +114,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text,
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
         }
         else if (node.type === 'horizontalRule') {
@@ -118,6 +124,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: '',
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
         }
         else if (node.type === 'table') {
@@ -128,6 +135,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: extractTableText(node),
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
             // Don't descend into table internals — the walker treats tables as opaque.
         }
@@ -138,6 +146,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: node.attrs?.alt || '',
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
         }
         else if (CONTAINER_TYPES.has(node.type)) {
@@ -149,6 +158,7 @@ function walkNodes(nodes, blocks, parentPosition) {
                 text: '',
                 parentPosition,
                 ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
             });
             walkNodes(node.content || [], blocks, containerPosition);
         }
@@ -235,15 +245,23 @@ export function applyIdsToTiptap(doc, pinnedByPosition) {
                     node.attrs.id = id;
                 }
                 position++;
-                // Descend into container children (matches walkNodes behavior).
-                // Tables and images are leaf-like in the walker; descend only for containers.
+                // Descend into container children, MIRRORING `walkNodes`/`tiptapToBlocks`.
+                // CRITICAL: tables are opaque to the walker (see `tiptapToBlocks` —
+                // emits one Block per table, doesn't descend). `applyIdsToTiptap` MUST
+                // use the same descent rule, otherwise position counters diverge and a
+                // matcher pin meant for a top-level node gets applied to a node inside
+                // a table. That's exactly the table-row-stole-the-paragraph-id
+                // corruption pattern (e.g. `tr:3141ee2a` where 3141ee2a was the
+                // target-total paragraph's ID).
+                //
+                // Descend ONLY into types `walkNodes` recursively descends into.
+                // adr: adr/node-identity-matcher.md
                 const isContainer = node.type === 'bulletList' ||
                     node.type === 'orderedList' ||
                     node.type === 'taskList' ||
                     node.type === 'listItem' ||
                     node.type === 'taskItem' ||
-                    node.type === 'blockquote' ||
-                    CONTAINER_TYPES.has(node.type);
+                    node.type === 'blockquote';
                 if (isContainer && node.content)
                     walk(node.content);
             }