openwriter 0.14.0 → 0.15.0

package/dist/server/state.js

@@ -3,17 +3,18 @@
  * Each document is a .md file in ~/.openwriter/ with YAML frontmatter.
  * Title lives in frontmatter metadata. Filenames are stable identifiers.
  */
-import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync, utimesSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync, utimesSync, watch } from 'fs';
 import { join } from 'path';
 import matter from 'gray-matter';
 import { tiptapToMarkdown, tiptapToMarkdownChecked, tiptapToBody, markdownToTiptap } from './markdown.js';
 import { applyTextEditsToNode } from './text-edit.js';
-import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync } from './helpers.js';
+import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath, canonicalizeIdentifier } from './helpers.js';
 import { snapshotIfNeeded, ensureDocId } from './versions.js';
 import { extractForwardLinks, extractForwardLinksFromDisk, updateBacklinksForSource } from './backlinks.js';
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
+import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
 /** Read the persisted identity graph (nodes + graveyard) from a file's
  *  frontmatter. This is the matcher's previousNodes baseline at save time —
  *  the disk is the source of truth, not a parallel in-memory cache. Returns
@@ -48,6 +49,8 @@ const DEFAULT_DOC = {
     content: [{ type: 'paragraph', content: [] }],
 };
 let state = {
+    canonical: DEFAULT_DOC,
+    overlay: new Map(),
     document: DEFAULT_DOC,
     title: 'Untitled',
     metadata: { title: 'Untitled' },
@@ -56,37 +59,396 @@ let state = {
     lastModified: new Date(),
     docId: '',
     originalFrontmatter: null,
+    loadedMtime: 0,
 };
+// ============================================================================
+// PRIMARY-STATE WRITE HELPERS
+// ============================================================================
+// All mutations to canonical or overlay go through these helpers. Each updates
+// the underlying state AND recomputes state.document so external readers via
+// getDocument() see the new merged view. Direct assignment to state.canonical,
+// state.overlay, or state.document is forbidden outside this module.
+// adr: adr/pending-overlay-model.md
+/** Recompute the merged view from primary state. Idempotent — running twice
+ *  produces the same result. */
+function recomputeMerged() {
+    state.document = applyOverlayPure(state.canonical, Array.from(state.overlay.values()));
+}
+/** Replace canonical wholesale. Used by load paths and accept-all flows. */
+function setCanonical(doc) {
+    state.canonical = doc;
+    recomputeMerged();
+}
+/** Replace overlay wholesale from an entry array. Dedupes by nodeId
+ *  (first occurrence wins; preserves original anchors). Preserves
+ *  addedAtVersion from any pre-existing state.overlay entry with the
+ *  same nodeId; stamps current docVersion on entries that are new. */
+function setOverlayFromEntries(entries) {
+    const currentVersion = getDocVersion();
+    const newOverlay = new Map();
+    for (const e of entries) {
+        if (newOverlay.has(e.nodeId))
+            continue;
+        const existing = state.overlay.get(e.nodeId);
+        const entry = { ...e };
+        if (existing?.addedAtVersion !== undefined) {
+            entry.addedAtVersion = existing.addedAtVersion;
+        }
+        else if (entry.addedAtVersion === undefined) {
+            entry.addedAtVersion = currentVersion;
+        }
+        newOverlay.set(e.nodeId, entry);
+    }
+    state.overlay = newOverlay;
+    recomputeMerged();
+}
+/** Replace primary state from a merged-shape doc. Splits via splitMergedDoc.
+ *  Used by paths that receive a merged doc (browser doc-updates, legacy
+ *  on-disk migration). */
+function setPrimaryFromMerged(merged) {
+    const { canonical, overlayEntries } = splitMergedDoc(merged);
+    state.canonical = canonical;
+    setOverlayFromEntries(overlayEntries);
+}
+/**
+ * Sync routing for a stale-version browser doc-update. The browser's
+ * submission was captured at server version `browserVersion`; the server
+ * has since advanced to a higher version because the agent wrote concurrently.
+ *
+ * Behavior: the browser's view of canonical is accepted as authoritative.
+ * The overlay merges browser's view with server's recent additions: any
+ * server overlay entry with addedAtVersion > browserVersion is an agent
+ * addition the browser hadn't seen, so it survives. Conflicting nodeIds
+ * (both browser and server have entries) → server wins, on the principle
+ * that an explicit agent proposal outranks a browser save that didn't see
+ * it. The user can reject the server's entry through the normal review UI
+ * if they disagree.
+ *
+ * Replaces the older "BLOCK stale doc-update" behavior — that pattern lost
+ * the user's typing without warning. The merge approach preserves both
+ * sides' work in the common case (disjoint touches) and surfaces conflicts
+ * (same-paragraph touches) via the existing pending-review UI.
+ *
+ * Returns the count of server overlay entries that were preserved.
+ * adr: adr/pending-overlay-model.md
+ */
+export function syncBrowserDocUpdate(browserDoc, browserVersion) {
+    const { canonical: browserCanonical, overlayEntries: browserOverlay } = splitMergedDoc(browserDoc);
+    // Identify server overlay entries to preserve: those added after browser's baseline.
+    const preserved = [];
+    for (const [, entry] of state.overlay) {
+        const added = entry.addedAtVersion ?? 0;
+        if (added > browserVersion)
+            preserved.push(entry);
+    }
+    // Build the merged overlay. Browser's view first; server-preserved entries
+    // overwrite (server wins on conflict).
+    const merged = new Map();
+    for (const e of browserOverlay) {
+        if (!merged.has(e.nodeId))
+            merged.set(e.nodeId, e);
+    }
+    for (const e of preserved) {
+        merged.set(e.nodeId, e);
+    }
+    // Apply: browser's canonical view + merged overlay.
+    state.canonical = browserCanonical;
+    setOverlayFromEntries(Array.from(merged.values()));
+    return { preservedServerEntries: preserved.length };
+}
 const listeners = new Set();
+const idRewriteListeners = new Set();
+const externalWriteConflictListeners = new Set();
+export function onExternalWriteConflict(listener) {
+    externalWriteConflictListeners.add(listener);
+    return () => externalWriteConflictListeners.delete(listener);
+}
+function notifyExternalWriteConflict(filePath, diskMtime, loadedMtime) {
+    for (const listener of externalWriteConflictListeners) {
+        try {
+            listener({ filePath, diskMtime, loadedMtime });
+        }
+        catch (err) {
+            console.error('[State] external-write listener threw:', err);
+        }
+    }
+}
+/**
+ * Check whether the active doc's on-disk mtime is newer than what we
+ * loaded/saved. Returns null when the doc has no file path, the file is
+ * gone, or there's no drift. Exposed for the get_pad_status MCP tool so
+ * agents can detect "you need to reload_from_disk before your next save"
+ * without waiting for the save itself to fail.
+ */
+export function getExternalMtimeDrift() {
+    if (!state.filePath || state.loadedMtime === 0)
+        return null;
+    try {
+        const diskMtime = statSync(state.filePath).mtimeMs;
+        if (diskMtime !== state.loadedMtime) {
+            return { diskMtime, loadedMtime: state.loadedMtime };
+        }
+    }
+    catch { /* file missing */ }
+    return null;
+}
+/** Force-refresh the active doc's loadedMtime snapshot to current disk mtime.
+ *  Used by reload_from_disk after re-reading the file, so the freshly
+ *  adopted content's mtime becomes our new baseline. */
+export function refreshLoadedMtime() {
+    if (!state.filePath)
+        return;
+    try {
+        state.loadedMtime = statSync(state.filePath).mtimeMs;
+    }
+    catch { /* best-effort */ }
+}
+// ============================================================================
+// ACTIVE DOC FILE WATCHER
+// ============================================================================
+//
+// Watches the currently-active doc's file for external writes. When any
+// other process (Edit tool, VSCode, a script) mutates the file, fs.watch
+// fires; we debounce burst events, verify the disk mtime actually advanced
+// past our last-stamped `loadedMtime`, and route through the unified
+// reloadActiveDocFromDisk pathway — which re-parses disk, re-attaches the
+// pending overlay by nodeId, runs the matcher, and lets subscribers
+// broadcast a document-reloaded message to clients.
+//
+// Why push (fs.watch) instead of pull (mtime poll on writes only):
+//   - The browser autosave race was: external editor writes → server's
+//     in-memory state is now stale → browser sends an autosave from BEFORE
+//     the external write → server's version counter hasn't advanced (no
+//     MCP write occurred) → version check passes → stale content clobbers
+//     the external write.
+//   - The fix is to advance docVersion the instant the file changes on
+//     disk, not the instant we try to save. fs.watch makes that immediate.
+//
+// Single watcher at a time: we only care about the active doc. Switching
+// docs tears down the previous watcher and opens a new one.
+//
+// Cross-platform: Node's fs.watch is inotify on Linux, FSEvents on macOS,
+// ReadDirectoryChangesW on Windows. Single-file watching is reliable on
+// all three; chokidar would add value for recursive directory trees, not
+// here.
+//
+// adr: adr/active-doc-watcher.md
+let activeWatcher = null;
+let activeWatcherPath = '';
+let watcherDebounceTimer = null;
+const documentReloadedListeners = new Set();
+export function onDocumentReloaded(listener) {
+    documentReloadedListeners.add(listener);
+    return () => documentReloadedListeners.delete(listener);
+}
+function notifyDocumentReloaded(event) {
+    for (const listener of documentReloadedListeners) {
+        try {
+            listener(event);
+        }
+        catch (err) {
+            console.error('[State] document-reloaded listener threw:', err);
+        }
+    }
+}
+/** Tear down the active-doc watcher (if any) and clear bookkeeping. */
+function stopActiveDocWatcher() {
+    if (watcherDebounceTimer) {
+        clearTimeout(watcherDebounceTimer);
+        watcherDebounceTimer = null;
+    }
+    if (activeWatcher) {
+        try {
+            activeWatcher.close();
+        }
+        catch { /* best-effort */ }
+        activeWatcher = null;
+    }
+    activeWatcherPath = '';
+}
+/** Handle a watcher event after debounce — reload if mtime actually advanced. */
+function handleWatcherEvent() {
+    // Only act if the watched path is still the active doc. If the user
+    // switched away during the debounce window, drop this event — the new
+    // active doc has its own watcher already running.
+    if (!state.filePath || state.filePath !== activeWatcherPath)
+        return;
+    // Skip if the file is gone (e.g., delete during watch). The next save
+    // will re-create it from in-memory state.
+    if (!existsSync(state.filePath))
+        return;
+    let diskMtime;
+    try {
+        diskMtime = statSync(state.filePath).mtimeMs;
+    }
+    catch {
+        return;
+    }
+    // Filter out events from our own writes. writeToDisk re-stamps
+    // state.loadedMtime to the post-write disk mtime, so by the time this
+    // handler fires for our own atomicWriteFileSync, mtimes match and we
+    // skip. Only genuine external writes have diskMtime > loadedMtime.
+    if (diskMtime === state.loadedMtime)
+        return;
+    const reloaded = reloadActiveDocFromDisk();
+    if (!reloaded)
+        return;
+    // Bump version so any in-flight stale browser autosave is rejected by
+    // the existing version check in the WS handler. Without this bump, the
+    // browser's pre-external-write state would silently overwrite the
+    // freshly-loaded disk content.
+    bumpDocVersion();
+    notifyDocumentReloaded({
+        filePath: state.filePath,
+        filename: reloaded.filename,
+        document: reloaded.document,
+        title: reloaded.title,
+        docId: state.docId,
+        metadata: state.metadata,
+        orphans: reloaded.orphans,
+        staleBaseline: reloaded.staleBaseline,
+    });
+    const orphanCount = reloaded.orphans.length;
+    const staleCount = reloaded.staleBaseline.length;
+    const suffix = orphanCount || staleCount
+        ? ` (${orphanCount} orphan, ${staleCount} stale-baseline pending entries)`
+        : '';
+    console.log(`[State] reload active doc from external write: ${reloaded.filename}${suffix}`);
+}
+/** Start (or restart) the watcher on the active doc's filePath. Called
+ *  whenever the active doc changes, or whenever load() lands a file. */
+export function startActiveDocWatcher() {
+    stopActiveDocWatcher();
+    if (!state.filePath || !existsSync(state.filePath))
+        return;
+    // Some test environments (Windows CI, ephemeral filesystems) error from
+    // fs.watch on transient files. Swallow the failure — we'll simply not
+    // have external-write detection for this doc, which is degraded but
+    // not broken. writeToDisk still has the loadedMtime guard as a backstop.
+    try {
+        activeWatcherPath = state.filePath;
+        activeWatcher = watch(state.filePath, { persistent: false }, () => {
+            // Burst-debounce: editors often write through a temp file + rename,
+            // which fires multiple events in rapid succession. 80ms is short
+            // enough that human-perceptible latency is unchanged and long
+            // enough that one logical save coalesces.
+            if (watcherDebounceTimer)
+                clearTimeout(watcherDebounceTimer);
+            watcherDebounceTimer = setTimeout(handleWatcherEvent, 80);
+        });
+        activeWatcher.on('error', (err) => {
+            console.error(`[State] active doc watcher error on ${activeWatcherPath}:`, err.message);
+            stopActiveDocWatcher();
+        });
+    }
+    catch (err) {
+        console.error(`[State] failed to watch ${state.filePath}:`, err?.message || err);
+        stopActiveDocWatcher();
+    }
+}
 // ============================================================================
 // EXTERNAL DOCUMENT REGISTRY
 // ============================================================================
 function getExternalDocsFile() { return join(getDataDir(), 'external-docs.json'); }
+/** External docs registered with openwriter — canonicalized paths only.
+ *  Adding via `registerExternalDoc` runs paths through `canonicalizePath`
+ *  before insertion, so the same physical file via any spelling
+ *  (forward/back slash, mixed case drive letter, symlink) collapses to a
+ *  single entry.
+ *  adr: adr/path-canonicalization.md */
 const externalDocs = new Set();
+// ============================================================================
+// AGENT-STUB REGISTRY (in-memory only — never persisted)
+// ============================================================================
+//
+// A doc is an "agent stub" between create_document (which mints an empty
+// shell) and populate_document + accept (which fills it with content). If
+// the user rejects the populated content, the stub is deleted — the agent
+// proposed a doc, the user declined, nothing should remain.
+//
+// HISTORICAL MISTAKE: stub status was stored as `agentCreated: true` in
+// frontmatter on disk. That made it sticky across sessions, server
+// restarts, and arbitrary file lifetimes. Any reject-all on a doc whose
+// stub status had been forgotten in a previous flow would destructively
+// delete a file with hours of accepted work. The fix is not "guard the
+// destruction more carefully"; the fix is "don't persist transient
+// session state to disk in the first place."
+//
+// Stub status is now an in-memory Set<filename> with process lifetime.
+//   - markAsAgentStub(filename) — called on create_document
+//   - unmarkAgentStub(filename) — called on any save that contains
+//     non-pending content (graduation), on accept-all, on rename
+//   - isAgentStub(filename) — the only thing reject-all-deletes consults
+//
+// A stub that survives a server restart is by definition no longer fresh.
+// It loads from disk like any other doc and reject-all will not delete it.
+// This is intentional: graduating-by-lifetime is the safest fallback.
+//
+// adr: adr/agent-stub-model.md
+const agentStubFilenames = new Set();
+export function markAsAgentStub(filename) {
+    if (filename)
+        agentStubFilenames.add(filename);
+}
+export function unmarkAgentStub(filename) {
+    if (filename)
+        agentStubFilenames.delete(filename);
+}
+export function isAgentStub(filename) {
+    return !!filename && agentStubFilenames.has(filename);
+}
+/** Legacy migration. If a file's frontmatter has `agentCreated: true`, that
+ *  field came from the pre-architectural-fix code path. Strip it on load so
+ *  we don't keep round-tripping a dead field. No in-memory stub registration
+ *  happens — by definition, if the flag survived to disk this long, the doc
+ *  is not a fresh stub anymore. */
+function stripLegacyAgentCreated(metadata) {
+    if (metadata && 'agentCreated' in metadata)
+        delete metadata.agentCreated;
+}
 function persistExternalDocs() {
     try {
         atomicWriteFileSync(getExternalDocsFile(), JSON.stringify([...externalDocs]));
     }
     catch { /* best-effort */ }
 }
+/** Load external-doc registry from disk and canonicalize every entry on
+ *  the way in. The Set's branded type collapses any pre-existing
+ *  duplicates (forward-slash vs backslash entries for the same file)
+ *  to one — that's the one-time migration. If canonicalization changed
+ *  the on-disk representation, we re-persist so the file matches
+ *  in-memory state.
+ *  adr: adr/path-canonicalization.md */
 function loadExternalDocs() {
     try {
-        if (existsSync(getExternalDocsFile())) {
-            const paths = JSON.parse(readFileSync(getExternalDocsFile(), 'utf-8'));
-            for (const p of paths) {
-                if (existsSync(p))
-                    externalDocs.add(p);
+        if (!existsSync(getExternalDocsFile()))
+            return;
+        const paths = JSON.parse(readFileSync(getExternalDocsFile(), 'utf-8'));
+        let needsRewrite = false;
+        for (const p of paths) {
+            if (!existsSync(p)) {
+                needsRewrite = true;
+                continue;
             }
+            const canon = canonicalizePath(p);
+            if (canon !== p)
+                needsRewrite = true;
+            externalDocs.add(canon);
+        }
+        // If the on-disk file had duplicates or non-canonical entries, the
+        // collapsed Set is now smaller and/or different — persist it back.
+        if (needsRewrite || externalDocs.size !== paths.length) {
+            persistExternalDocs();
         }
     }
     catch { /* corrupt file — start fresh */ }
 }
 export function registerExternalDoc(fullPath) {
-    externalDocs.add(fullPath);
+    externalDocs.add(canonicalizePath(fullPath));
     persistExternalDocs();
 }
 export function unregisterExternalDoc(fullPath) {
-    externalDocs.delete(fullPath);
+    externalDocs.delete(canonicalizePath(fullPath));
     persistExternalDocs();
 }
 export function getExternalDocs() {
@@ -110,6 +472,20 @@ function isDocEmpty(doc) {
 export function getDocument() {
     return state.document;
 }
+/** The clean canonical document — what disk holds, what the matcher pairs
+ *  against, what snapshots capture. Primary state; not derived. */
+export function getCanonical() {
+    return state.canonical;
+}
+/** Snapshot of the structured pending overlay. Primary state. */
+export function getOverlayEntries() {
+    return Array.from(state.overlay.values());
+}
+/** Read-only view of the overlay Map. Use when you need keyed lookup
+ *  rather than iteration. */
+export function getOverlay() {
+    return state.overlay;
+}
 export function getTitle() {
     return state.title;
 }
@@ -409,7 +785,10 @@ export function updateDocument(doc) {
     if (serverHadPending) {
         transferPendingAttrs(state.document, doc);
     }
-    state.document = doc;
+    // Route the incoming merged-shape doc through the primary-state setter
+    // so canonical + overlay get refreshed and state.document is the
+    // recomputed merged view. Direct assignment is forbidden.
+    setPrimaryFromMerged(doc);
     state.lastModified = new Date();
     // Validate: if server had pending changes, verify they survived the transfer
     if (serverHadPending && !hasPendingChanges()) {
@@ -479,15 +858,58 @@ function transferPendingAttrs(source, target) {
 // ============================================================================
 // AGENT WRITE LOCK
 // ============================================================================
+// adr: adr/agent-lock-per-doc.md
 const AGENT_LOCK_MS = 3000; // Block browser doc-updates for 3s after agent write
-let lastAgentWriteTime = 0;
-/** Set the agent write lock (called after agent changes). */
-export function setAgentLock() {
-    lastAgentWriteTime = Date.now();
-}
-/** Check if the agent write lock is active. */
-export function isAgentLocked() {
-    return Date.now() - lastAgentWriteTime < AGENT_LOCK_MS;
+const lockExpiry = new Map();
+let globalLockExpiry = 0;
+/** Derive the identifier used for locking the active doc. Mirrors
+ *  documents.ts:getActiveFilename without importing it (circular dep). */
+function activeDocLockKey() {
+    const fp = state.filePath;
+    if (!fp)
+        return '';
+    if (isExternalDoc(fp))
+        return canonicalizeIdentifier(fp);
+    return fp.split(/[/\\]/).pop() || '';
+}
+/** Set the agent write lock for a specific document. */
+export function setAgentLock(filename) {
+    if (!filename) {
+        // Defensive: empty filename means we don't know what to lock — lock global.
+        setAgentLockGlobal();
+        return;
+    }
+    const key = canonicalizeIdentifier(filename);
+    const wasActive = (lockExpiry.get(key) ?? 0) > Date.now();
+    lockExpiry.set(key, Date.now() + AGENT_LOCK_MS);
+    diagLog(`[Lock] SET filename=${key} ttl=${AGENT_LOCK_MS}ms${wasActive ? ' (extends active lock)' : ''}`);
+}
+/** Lock the currently active document. Convenience for callers that mutate
+ *  via state.filePath rather than an explicit filename. */
+export function setAgentLockActive() {
+    setAgentLock(activeDocLockKey());
+}
+/** Lock every document briefly. Used at server init so reconnecting browsers
+ *  can't push stale state from before the restart. */
+export function setAgentLockGlobal() {
+    globalLockExpiry = Date.now() + AGENT_LOCK_MS;
+    diagLog(`[Lock] SET global ttl=${AGENT_LOCK_MS}ms`);
+}
+/** Check if the agent write lock is active for a given document. */
+export function isAgentLocked(filename) {
+    const now = Date.now();
+    if (globalLockExpiry > now)
+        return true;
+    if (!filename)
+        return false;
+    const key = canonicalizeIdentifier(filename);
+    const expiry = lockExpiry.get(key);
+    if (expiry === undefined)
+        return false;
+    if (expiry > now)
+        return true;
+    lockExpiry.delete(key);
+    return false;
 }
 // ---- Document version counter: prevents stale browser doc-updates ----
 let docVersion = 0;
@@ -508,9 +930,16 @@ export function resetDocVersion() {
     docVersion = 0;
 }
 // ---- Debounced save: coalesces rapid agent writes into a single disk write ----
+//
+// Single timer for the entire process. Both state.ts (MCP write paths, applyChanges,
+// updateDocument) and ws.ts (browser doc-update, pending-resolved) call into this.
+// Previously each module had its own timer (state.ts 500ms, ws.ts 2s) which meant
+// a save could be armed by one path, reset by another, and fire on a delay that
+// matched neither documented value. One timer, one TTL — predictable.
+// adr: adr/pending-overlay-model.md
 let saveTimer = null;
 const SAVE_DEBOUNCE_MS = 500;
-function debouncedSave() {
+export function debouncedSave() {
     if (saveTimer)
         clearTimeout(saveTimer);
     saveTimer = setTimeout(() => {
@@ -530,7 +959,7 @@ export function applyChanges(changes) {
     const processed = applyChangesToDocument(changes);
     // Bump version + lock browser doc-updates to prevent stale state overwrite
     const version = bumpDocVersion();
-    setAgentLock();
+    setAgentLockActive();
     // Broadcast processed changes (with server-assigned IDs + version) to browser clients
     for (const listener of listeners) {
         listener(processed, version);
@@ -554,6 +983,10 @@ export function applyChanges(changes) {
     }
     return { count: processed.length, lastNodeId };
 }
+export function onIdRewrites(listener) {
+    idRewriteListeners.add(listener);
+    return () => idRewriteListeners.delete(listener);
+}
 export function onChanges(listener) {
     listeners.add(listener);
     return () => listeners.delete(listener);
@@ -562,6 +995,24 @@ export function onChanges(listener) {
 // SERVER-SIDE DOCUMENT MUTATIONS
 // ============================================================================
 // generateNodeId imported from helpers.ts
+/**
+ * Containers whose internals are NOT addressable via MCP. `findNode` must not
+ * descend into these — their child IDs are ephemeral (regenerated every
+ * `markdownToTiptap` parse, untracked by the matcher) and never exposed via
+ * `compactNodes`, so any agent-provided ID that happens to match a node inside
+ * one is a collision, not a legitimate target.
+ *
+ * Before this guard existed, a `write_to_pad` rewrite could silently corrupt a
+ * table cell: an agent ID collision with a freshly-minted table-internal node
+ * routed the splice into the table instead of the intended top-level
+ * paragraph. Reported as success, observable as stray paragraphs / mangled
+ * rows in the saved markdown.
+ *
+ * Mirrors `node-blocks.ts`'s walker, which already treats tables as opaque.
+ *
+ * adr: adr/node-identity-matcher.md
+ */
+const OPAQUE_CONTAINER_TYPES = new Set(['table', 'tableRow', 'tableCell', 'tableHeader']);
 /**
  * Find a node by ID in any document tree.
  * topLevel is used to resolve the "end" sentinel.
@@ -577,6 +1028,11 @@ function findNode(nodes, id, topLevel) {
         if (nodes[i].attrs?.id === id) {
             return { parent: nodes, index: i };
         }
+        // Don't descend into table internals (table, tableRow, tableCell, tableHeader).
+        // Their IDs aren't addressable via MCP and they regenerate on every parse,
+        // so any match inside is a collision that would silently corrupt the table.
+        if (OPAQUE_CONTAINER_TYPES.has(nodes[i].type))
+            continue;
         if (nodes[i].content && Array.isArray(nodes[i].content)) {
             const result = findNode(nodes[i].content, id, topLevel);
             if (result)
@@ -845,12 +1301,23 @@ export function isAutoAcceptActive(filename, metadata) {
         return false;
     return isAutoAcceptInheritedForDoc(filename);
 }
-/** Apply changes to the active document singleton. */
+/** Apply changes to the active document singleton.
+ *
+ *  The applyChangesToDoc engine mutates the merged view (state.document) —
+ *  it's where the pending-status stamping logic lives. After the mutation,
+ *  re-split state.document back into primary state (canonical + overlay) so
+ *  the cache + matcher + save paths see consistent primary state. The
+ *  re-split is the bridge between the legacy "mutate merged in place" engine
+ *  and the new "primary state is canonical + overlay" model. */
 function applyChangesToDocument(changes) {
     const autoAccept = isAutoAcceptActive(activeDocFilename(), state.metadata);
     const processed = applyChangesToDoc(state.document, changes, autoAccept);
     if (processed.length > 0) {
         state.lastModified = new Date();
+        // Re-sync primary state from the now-mutated merged view. Idempotent:
+        // splitMergedDoc + applyOverlayPure round-trip leaves state.document
+        // structurally equivalent to itself.
+        setPrimaryFromMerged(state.document);
     }
     return processed;
 }
@@ -864,8 +1331,16 @@ export function applyTextEdits(nodeId, edits) {
         return { success: false, error: `Node ${nodeId} not found` };
     const originalNode = found.parent[found.index];
     const result = applyTextEditsToNode(originalNode, edits);
-    if (!result)
-        return { success: false, error: 'No edits matched' };
+    if (!result) {
+        // Surface a slice of the actual node text alongside the searched `find`
+        // strings so the agent can diff for unicode/whitespace mismatches
+        // (em-dash vs hyphen-minus, NBSP vs space, smart quotes, etc.). Without
+        // this the failure is opaque and the agent has to guess.
+        const nodeText = extractText(originalNode.content || []);
+        const truncated = nodeText.length > 240 ? nodeText.slice(0, 240) + '…' : nodeText;
+        const searched = edits.map((e) => JSON.stringify(e.find)).join(', ');
+        return { success: false, error: `No edits matched in node ${nodeId}. Searched: ${searched}. Node text starts: ${JSON.stringify(truncated)}` };
+    }
     // Inline edit decoration only matters when there's a review surface — skip in autoAccept.
     if (!isAutoAcceptActive(activeDocFilename(), state.metadata)) {
         result.node.attrs = {
@@ -888,14 +1363,42 @@ export function applyTextEdits(nodeId, edits) {
  *  (Option B in adr/node-identity-matcher.md). Markdown is the source of
  *  truth; memory is an ephemeral working copy. */
 export function setActiveDocument(doc, title, filePath, isTemp, lastModified, metadata, originalFrontmatter) {
-    state.document = doc;
+    // Route the incoming doc through the primary-state setter — splits into
+    // canonical + overlay (handles legacy in-frontmatter pending if present)
+    // and recomputes the merged view.
+    setPrimaryFromMerged(doc);
     state.title = title;
     state.metadata = metadata || { title };
-    state.filePath = filePath;
+    // Legacy: strip any pre-architectural-fix `agentCreated` field that
+    // arrived in metadata (e.g. from a re-parse of an old on-disk file).
+    // The in-memory agentStubFilenames Set is the only authority for stub
+    // status — disk frontmatter must not carry stub state.
+    stripLegacyAgentCreated(state.metadata);
+    // Canonicalize at the identity boundary: same physical file via any
+    // spelling (forward/back slash, drive-letter case, symlink) lands the
+    // same string in state.filePath, which is the cache key for the doc
+    // cache and the subscription path for the fs watcher.
+    // adr: adr/path-canonicalization.md
+    state.filePath = filePath ? canonicalizePath(filePath) : '';
     state.isTemp = isTemp;
     state.lastModified = lastModified || new Date();
     state.docId = ensureDocId(state.metadata);
     state.originalFrontmatter = originalFrontmatter ?? null;
+    // Snapshot the on-disk mtime so writeToDisk can detect external writes
+    // that land while this doc is active. 0 = no file on disk yet (new doc).
+    try {
+        state.loadedMtime = filePath && existsSync(filePath) ? statSync(filePath).mtimeMs : 0;
+    }
+    catch {
+        state.loadedMtime = 0;
+    }
+    // Pending overlay rehydration. See mergeOverlayOnLoad for the three cases
+    // (sidecar present, legacy migration, no pending).
+    mergeOverlayOnLoad();
+    // Subscribe the fs watcher to this doc so external writes (Edit tool,
+    // VSCode, scripts) trigger a unified reload + version bump + broadcast.
+    // adr: adr/active-doc-watcher.md
+    startActiveDocWatcher();
 }
 // ============================================================================
 // PENDING DOCUMENT CACHE (avoids disk scans on every broadcast)
@@ -965,7 +1468,12 @@ function populatePendingCache() {
         catch { /* skip unreadable files */ }
     }
 }
-const docCache = new Map(); // key = filePath
+/** Keyed by canonical path. Two spellings of the same physical file
+ *  (forward/back slash, drive-letter case) collapse to one cache entry —
+ *  preventing parallel state where the same disk file lives in two
+ *  cache slots.
+ *  adr: adr/path-canonicalization.md */
+const docCache = new Map();
 /** Cache the active document's full state, keyed by filePath. Call after save().
  *
  *  Identity (nodes + graveyard) is NOT cached — the save-time matcher reads
@@ -979,8 +1487,14 @@ export function cacheActiveDocument() {
         fileMtime = statSync(state.filePath).mtimeMs;
     }
     catch { /* file may not exist yet */ }
-    docCache.set(state.filePath, {
-        document: structuredClone(state.document),
+    // Split the live merged document into canonical + overlay AT cache time —
+    // this is what protects against the duplicate-insert bug. Storing merged
+    // and re-applying overlay later was the broken pattern.
+    const split = splitMergedDoc(state.document);
+    docCache.set(canonicalizePath(state.filePath), {
+        canonical: split.canonical,
+        overlayEntries: split.overlayEntries,
+        document: applyOverlayPure(split.canonical, split.overlayEntries),
         metadata: structuredClone(state.metadata),
         title: state.title,
         isTemp: state.isTemp,
@@ -992,27 +1506,28 @@ export function cacheActiveDocument() {
 }
 /** Get a cached document if the file hasn't been modified externally. Returns null on miss or stale. */
 export function getCachedDocument(filePath) {
-    const cached = docCache.get(filePath);
+    const key = canonicalizePath(filePath);
+    const cached = docCache.get(key);
     if (!cached)
         return null;
     try {
         const currentMtime = statSync(filePath).mtimeMs;
         if (currentMtime !== cached.fileMtime) {
             // File changed on disk — invalidate cache
-            docCache.delete(filePath);
+            docCache.delete(key);
             return null;
         }
     }
     catch {
         // File doesn't exist or can't be read — invalidate
-        docCache.delete(filePath);
+        docCache.delete(key);
         return null;
     }
     return cached;
 }
 /** Remove a specific file from the document cache. */
 export function invalidateDocCache(filePath) {
-    docCache.delete(filePath);
+    docCache.delete(canonicalizePath(filePath));
 }
 /** Update the cache entry for a file after writing changes (without cloning the active state). */
 export function updateCacheEntry(filePath, doc, title, metadata, isTemp, docId) {
@@ -1021,10 +1536,18 @@ export function updateCacheEntry(filePath, doc, title, metadata, isTemp, docId)
         fileMtime = statSync(filePath).mtimeMs;
     }
     catch { /* best-effort */ }
+    const key = canonicalizePath(filePath);
     // Preserve originalFrontmatter from existing cache entry (if any)
-    const existing = docCache.get(filePath);
-    docCache.set(filePath, {
-        document: structuredClone(doc),
+    const existing = docCache.get(key);
+    // Split the incoming doc into canonical + overlay before caching so the
+    // cache stores canonical-only and the duplicate-insert chain is broken.
+    const split = splitMergedDoc(doc);
+    const overlayEntries = split.overlayEntries;
+    const canonicalClone = split.canonical;
+    docCache.set(key, {
+        canonical: canonicalClone,
+        overlayEntries,
+        document: applyOverlayPure(canonicalClone, overlayEntries),
         metadata: structuredClone(metadata),
         title,
         isTemp,
@@ -1036,10 +1559,15 @@ export function updateCacheEntry(filePath, doc, title, metadata, isTemp, docId)
 }
 /** Reset all in-memory caches. Called on profile switch. */
 export function clearAllCaches() {
+    // Tear down the active-doc watcher before swapping state — leaving it
+    // alive would point at a path the new profile doesn't own.
+    stopActiveDocWatcher();
     docCache.clear();
     pendingDocCache.clear();
     externalDocs.clear();
     state = {
+        canonical: DEFAULT_DOC,
+        overlay: new Map(),
         document: DEFAULT_DOC,
         title: 'Untitled',
         metadata: { title: 'Untitled' },
@@ -1048,6 +1576,7 @@ export function clearAllCaches() {
         lastModified: new Date(),
         docId: '',
         originalFrontmatter: null,
+        loadedMtime: 0,
     };
 }
 // ============================================================================
@@ -1069,23 +1598,225 @@ export function hasPendingChanges(doc) {
     }
     return scan(target.content);
 }
-/** Strip all pending attrs from the current document (after browser resolves all changes). */
+/** Strip all pending attrs from the current document (after browser resolves all changes).
+ *  In the new model this is implemented by clearing the overlay — the merged
+ *  view recomputes to canonical (which already has no pending markers). */
 export function stripPendingAttrs() {
-    function strip(nodes) {
-        if (!nodes)
+    state.overlay = new Map();
+    recomputeMerged();
+    removePendingCacheEntry(activeDocFilename());
+}
+/**
+ * Return a deep clone of `doc` with all pending changes reverted, as if the
+ * user had rejected every pending decoration:
+ *   - pendingStatus=insert   → drop the node
+ *   - pendingStatus=rewrite  → replace node with `pendingOriginalContent` (or drop if absent)
+ *   - pendingStatus=delete   → keep node, clear pending attrs (the rejection is "no, don't delete")
+ *   - no pendingStatus       → keep node, strip any stray pending attrs
+ *
+ * Used by `restore_version` to write a canonical-only safety checkpoint so
+ * the snapshot represents a clean recovery point rather than a flattened
+ * pending+canonical hybrid that never actually existed in the user's view.
+ *
+ * Does NOT mutate the input doc.
+ */
+/**
+ * Reload the active doc from disk. Re-reads the canonical .md file, applies
+ * the pending overlay from the sidecar (with orphan + stale-baseline
+ * classification), and updates state.document, state.metadata, state.title,
+ * and state.loadedMtime in place.
+ *
+ * Called by:
+ *   - chokidar watcher when an external write modifies the active file
+ *   - mcp.restore_version after writing the snapshot's content to disk
+ *   - mcp.reload_from_disk tool (explicit user-driven reload)
+ *   - writeToDisk's mtime-CAS backstop (recover-and-retry path)
+ *
+ * Returns the reload result so callers can broadcast or react to the
+ * orphan / staleBaseline classifications. Returns null if there's no
+ * active file path to reload (no-op).
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+export function reloadActiveDocFromDisk() {
+    if (!state.filePath || !existsSync(state.filePath))
+        return null;
+    const raw = readFileSync(state.filePath, 'utf-8');
+    const parsed = markdownToTiptap(raw);
+    // Split parsed doc: canonical (clean) + any legacy in-frontmatter pending.
+    const { canonical, overlayEntries: legacyOverlay } = splitMergedDoc(parsed.document);
+    state.title = parsed.title;
+    state.metadata = parsed.metadata;
+    stripLegacyAgentCreated(state.metadata);
+    state.docId = ensureDocId(state.metadata);
+    state.lastModified = new Date(statSync(state.filePath).mtimeMs);
+    state.loadedMtime = statSync(state.filePath).mtimeMs;
+    // Sidecar is authoritative if present. Otherwise legacy in-doc pending
+    // migrates to sidecar (one-time).
+    const sidecar = loadOverlay(state.docId);
+    let entries;
+    if (sidecar.length > 0) {
+        entries = sidecar;
+    }
+    else if (legacyOverlay.length > 0) {
+        entries = legacyOverlay;
+        saveOverlay(state.docId, legacyOverlay);
+    }
+    else {
+        entries = [];
+    }
+    // Set primary state directly — canonical from disk parse, overlay from
+    // sidecar (or legacy migration). Recompute merged via the helper.
+    state.canonical = canonical;
+    setOverlayFromEntries(entries);
+    return {
+        document: state.document,
+        title: state.title,
+        filename: state.filePath.split(/[/\\]/).pop() || '',
+        orphans: [],
+        staleBaseline: [],
+    };
+}
+/**
+ * Pending overlay rehydration. Runs after a doc loads from disk (load() or
+ * setActiveDocument). Three cases:
+ *
+ *   1. Sidecar has entries: state.document is canonical (parser found no
+ *      `meta.pending`). Apply sidecar overlay to layer pending decorations
+ *      back onto the canonical tree.
+ *
+ *   2. Sidecar empty, parser stamped pending attrs from legacy frontmatter:
+ *      one-time migration. Extract overlay from state.document, save to
+ *      sidecar. State.document already has pending attrs from parse, so
+ *      no apply step needed.
+ *
+ *   3. Sidecar empty, parser stamped nothing: no pending state. No-op.
+ *
+ * Returns the merged overlay entries for callers that need them.
+ * adr: adr/pending-overlay-model.md
+ */
+function mergeOverlayOnLoad() {
+    if (!state.docId)
+        return [];
+    // setActiveDocument just populated primary state via setPrimaryFromMerged.
+    // If a sidecar exists for this docId, it overrides any legacy in-doc pending
+    // that the splitter extracted from the input. If no sidecar exists and the
+    // legacy split found entries, persist them as a one-time migration.
+    const sidecar = loadOverlay(state.docId);
+    const legacy = Array.from(state.overlay.values());
+    if (sidecar.length > 0) {
+        setOverlayFromEntries(sidecar);
+        return sidecar;
+    }
+    else if (legacy.length > 0) {
+        saveOverlay(state.docId, legacy);
+        // overlay already has these entries from setPrimaryFromMerged; no-op
+        return legacy;
+    }
+    return [];
+}
+/**
+ * Apply an oldId → newId translation map to a TipTap doc tree in place.
+ * Used by writeToDisk to bring state.document's nodeIds in sync with the
+ * matcher's post-pass canonical IDs.
+ */
+function applyIdTranslationToDoc(doc, translation) {
+    if (translation.size === 0)
+        return;
+    function walk(nodes) {
+        if (!Array.isArray(nodes))
             return;
         for (const node of nodes) {
-            if (node.attrs?.pendingStatus) {
-                delete node.attrs.pendingStatus;
-                delete node.attrs.pendingOriginalContent;
-                delete node.attrs.pendingTextEdits;
+            const oldId = node?.attrs?.id;
+            if (oldId && translation.has(oldId)) {
+                node.attrs.id = translation.get(oldId);
             }
-            if (node.content)
-                strip(node.content);
+            if (node?.content)
+                walk(node.content);
         }
     }
-    strip(state.document.content);
-    removePendingCacheEntry(activeDocFilename());
+    walk(doc.content || []);
+}
+export function cloneWithPendingReverted(doc) {
+    const PENDING_KEYS = ['pendingStatus', 'pendingOriginalContent', 'pendingGroupId', 'pendingTextEdits', 'pendingSelectionFrom', 'pendingSelectionTo', 'pendingOriginalFrom', 'pendingOriginalTo', 'pendingOrphan', 'pendingStaleBaseline'];
+    function clean(node) {
+        const clone = JSON.parse(JSON.stringify(node));
+        if (clone.attrs) {
+            for (const k of PENDING_KEYS)
+                delete clone.attrs[k];
+        }
+        if (clone.content)
+            clone.content = walk(clone.content);
+        return clone;
+    }
+    function walk(nodes) {
+        const result = [];
+        for (const node of nodes) {
+            const status = node.attrs?.pendingStatus;
+            if (status === 'insert')
+                continue; // drop fresh agent inserts
+            if (status === 'rewrite') {
+                const original = node.attrs?.pendingOriginalContent;
+                if (original)
+                    result.push(clean(original));
+                // If no original stashed, drop the node — we have nothing to revert to.
+                continue;
+            }
+            // 'delete' status or no status: keep the node, strip any pending attrs.
+            result.push(clean(node));
+        }
+        return result;
+    }
+    return { type: 'doc', content: walk(doc.content || []) };
+}
+/**
+ * Does the document have any "accepted" content — i.e. blocks that wouldn't
+ * vanish under reject-all? Used to clear the `agentCreated` flag once a stub
+ * has graduated into a real document, so a later reject-all on stale pending
+ * decorations doesn't accidentally trigger the delete-on-reject cascade.
+ *
+ * A node counts as accepted if it has no pendingStatus, or has
+ * pendingStatus=delete (reject keeps the node), or pendingStatus=rewrite with
+ * `pendingOriginalContent` present (reject restores prior content).
+ */
+export function hasAcceptedContent(doc) {
+    function extractTextLocal(nodes) {
+        let out = '';
+        for (const n of nodes) {
+            if (typeof n.text === 'string')
+                out += n.text;
+            if (n.content)
+                out += extractTextLocal(n.content);
+        }
+        return out;
+    }
+    function walk(nodes) {
+        if (!nodes)
+            return false;
+        for (const node of nodes) {
+            const status = node.attrs?.pendingStatus;
+            // Nodes that would NOT survive reject-all: skip entirely, including their
+            // children. Otherwise an insert-pending paragraph's text children would be
+            // misread as accepted content.
+            if (status === 'insert')
+                continue;
+            if (status === 'rewrite' && !node.attrs?.pendingOriginalContent)
+                continue;
+            // This node survives reject-all (no status, or delete, or rewrite-with-original).
+            const surfaceText = node.text || extractTextLocal(node.content || []);
+            if (surfaceText && surfaceText.trim().length > 0)
+                return true;
+            // Non-text leaf types also count as accepted content
+            if (node.type === 'image' || node.type === 'horizontalRule' || node.type === 'table')
+                return true;
+            // Recurse into container nodes (lists, blockquotes) only when the
+            // container itself isn't a dropped-on-reject node.
+            if (node.content && walk(node.content))
+                return true;
+        }
+        return false;
+    }
+    return walk(doc.content || []);
 }
 /**
  * Mark leaf block nodes as pending within a node array.
@@ -1146,54 +1877,145 @@ function writeToDisk() {
         }
         catch { /* best-effort */ }
     }
+    // Stub graduation: once the doc contains accepted content, it's no longer
+    // a fresh stub. Remove it from the in-memory stub registry so reject-all
+    // can never trigger the cleanup-delete on it.
+    // adr: adr/agent-stub-model.md
+    if (hasAcceptedContent(state.document)) {
+        unmarkAgentStub(activeDocFilename());
+    }
+    // Defensive: never serialize `agentCreated` to disk. The field is dead;
+    // any code reading it would be the bug, not the field's presence.
+    if (state.metadata)
+        stripLegacyAgentCreated(state.metadata);
     let markdown;
     if (isExternalDoc(state.filePath)) {
-        // External files: preserve original frontmatter verbatim, no OpenWriter metadata injected
+        // External files: preserve original frontmatter verbatim, no OpenWriter metadata injected.
+        // External docs don't participate in the pending overlay system (the external editor
+        // is the source of truth for the file's structure).
         const body = tiptapToBody(state.document).replace(/(?:\s*<!-- -->\s*)+$/, '\n');
         markdown = state.originalFrontmatter
             ? `---\n${state.originalFrontmatter}\n---\n\n${body}`
             : body;
     }
     else {
-        // Save-time matcher pass (Option B: disk is the source of truth).
+        // Save-time matcher pass + pending overlay split.
+        //
+        // Architectural model: disk is canonical only. Pending state lives in a
+        // sidecar at `_pending/{docId}.json`. We split state.document into:
+        //   - canonical: a clone with all pending reverted (matcher operates on this)
+        //   - overlay: the extracted pending entries (saved to sidecar)
         //
-        // Read the existing file's frontmatter to recover previousNodes +
-        // graveyard, run the matcher against the current TipTap tree, and apply
-        // pinned IDs back onto the tree. Without this, type-change and
-        // graveyard-restore never fire within a session — the editor mints fresh
-        // IDs at insert time and the load-time matcher only sees the post-edit
-        // state. Memory holds no identity cache; identity always re-derives from
-        // disk at the save boundary.
+        // The matcher runs on canonical so the on-disk `nodes:` fingerprints match
+        // the on-disk body. Pre-matcher canonical IDs are translated to post-matcher
+        // IDs and the same translation is applied to (a) state.document, so the
+        // in-memory tree stays consistent with disk, and (b) the overlay entries,
+        // so they re-anchor correctly on reload.
         //
-        // adr: adr/node-identity-matcher.md
+        // adr: adr/node-identity-matcher.md · adr: adr/pending-overlay-model.md
+        const canonical = cloneWithPendingReverted(state.document);
         const { previousNodes, graveyard } = readPersistedIdentity(state.filePath);
         let nextGraveyard = graveyard;
+        const idTranslation = new Map();
         if (previousNodes.length > 0) {
-            const newBlocks = tiptapToBlocks(state.document);
+            const newBlocks = tiptapToBlocks(canonical);
+            const beforeIds = newBlocks.map((b) => b.id);
             const matchResult = matchNodes(previousNodes, newBlocks, { graveyard });
             const pinnedByPosition = new Map();
             for (const p of matchResult.pinned)
                 pinnedByPosition.set(p.position, p.id);
-            applyIdsToTiptap(state.document, pinnedByPosition);
+            applyIdsToTiptap(canonical, pinnedByPosition);
             nextGraveyard = matchResult.nextGraveyard;
+            // Build pre→post id translation (canonical's IDs match state.document's
+            // IDs at non-insert positions, since cloneWithPendingReverted preserves
+            // IDs on rewrite/delete/passthrough nodes).
+            for (let i = 0; i < beforeIds.length; i++) {
+                const oldId = beforeIds[i];
+                const newId = pinnedByPosition.get(i);
+                if (oldId && newId && oldId !== newId) {
+                    idTranslation.set(oldId, newId);
+                }
+            }
+            // Apply translation to primary state. The matcher renamed IDs on
+            // canonical (above); we need state.canonical, state.overlay's entry
+            // keys (the nodeId fields), and state.document to all see the new IDs.
+            if (idTranslation.size > 0) {
+                applyIdTranslationToDoc(state.canonical, idTranslation);
+                // Translate overlay entry nodeIds (rewrite/delete entries point at
+                // canonical IDs that may have shifted; insert entries have unique
+                // IDs not in the translation map and pass through).
+                const newOverlay = new Map();
+                for (const [nodeId, entry] of state.overlay) {
+                    const newNodeId = idTranslation.get(nodeId) ?? nodeId;
+                    newOverlay.set(newNodeId, { ...entry, nodeId: newNodeId });
+                }
+                state.overlay = newOverlay;
+                recomputeMerged();
+            }
+            // Broadcast id-rewrites so browser clients converge their TipTap state.
+            if (idRewriteListeners.size > 0 && idTranslation.size > 0) {
+                const rewrites = Array.from(idTranslation, ([oldId, newId]) => ({ oldId, newId }));
+                for (const listener of idRewriteListeners)
+                    listener(rewrites);
+            }
+        }
+        // Persist the structured overlay to sidecar. state.overlay IS the overlay
+        // in the new model — no extraction needed.
+        if (state.docId) {
+            saveOverlay(state.docId, Array.from(state.overlay.values()));
         }
         // Pass graveyard through metadata so the serializer can emit it in frontmatter.
         const metaWithGraveyard = nextGraveyard.length > 0
             ? { ...state.metadata, graveyard: nextGraveyard.map((g) => ({ id: g.id, fp: g.fingerprint })) }
             : state.metadata;
-        // Checked serializer — verifies the TipTap → markdown → TipTap round-trip
-        // preserves block shape. Logs to console on drift; never blocks the save.
-        const result = tiptapToMarkdownChecked(state.document, state.title, metaWithGraveyard);
+        // Checked serializer — operates on canonical (already pending-reverted).
+        // The serializer no longer emits `meta.pending` (overlay handles that).
+        const result = tiptapToMarkdownChecked(canonical, state.title, metaWithGraveyard);
         markdown = result.markdown;
     }
     if (existsSync(state.filePath)) {
         // Skip write if content is identical (prevents phantom git changes on doc switch)
         try {
             const existing = readFileSync(state.filePath, 'utf-8');
-            if (existing === markdown)
+            if (existing === markdown) {
+                // Even on a no-op write, refresh our mtime snapshot so we don't
+                // misread a stale `loadedMtime` as evidence of an external write.
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
                 return;
+            }
         }
         catch { /* read failed, proceed with write */ }
+        // EXTERNAL-WRITE GUARD: if disk mtime is newer than the mtime we stamped
+        // at load (or our last successful save), an external writer modified the
+        // file out from under us. Blindly writing our in-memory state would
+        // clobber their content silently. Block the write, log, and surface via
+        // sync-status so the agent/user can resolve via reload_from_disk.
+        //
+        // Edge cases handled:
+        //   - First save of a new doc: loadedMtime=0, so the guard never fires
+        //     (every real file's mtime will be > 0).
+        //   - Atomic-write race: writeFileSync momentarily mtime-bumps. We re-
+        //     stamp loadedMtime AFTER every successful own write so subsequent
+        //     guard checks compare against our own write, not a phantom delta.
+        //   - Clock drift: we compare exact ms equality (not >); any change at
+        //     all is treated as external. Filesystems guarantee monotonic mtime
+        //     per file on the same host so this is safe.
+        if (state.loadedMtime > 0) {
+            try {
+                const diskMtime = statSync(state.filePath).mtimeMs;
+                if (diskMtime !== state.loadedMtime) {
+                    console.error(`[State] BLOCKED save: external write detected on ${state.filePath} ` +
+                        `(disk mtime ${new Date(diskMtime).toISOString()} != loaded mtime ${new Date(state.loadedMtime).toISOString()}). ` +
+                        `Call reload_from_disk to adopt external content, or write_to_pad to re-apply changes on top.`);
+                    notifyExternalWriteConflict(state.filePath, diskMtime, state.loadedMtime);
+                    return;
+                }
+            }
+            catch { /* stat failed, proceed with save */ }
+        }
         // Safety: don't overwrite a file with substantial content using near-empty content.
         // Prevents save cascades where empty editor state destroys chapter files.
         // Exception: docs with pending changes may legitimately be smaller (agent replaced content).
@@ -1209,6 +2031,12 @@ function writeToDisk() {
         }
     }
     atomicWriteFileSync(state.filePath, markdown);
+    // Re-stamp loadedMtime so the next save's guard compares against our own
+    // most-recent write, not the prior load's mtime.
+    try {
+        state.loadedMtime = statSync(state.filePath).mtimeMs;
+    }
+    catch { /* best-effort */ }
     // Best-effort version snapshot — never blocks saves
     try {
         snapshotIfNeeded(state.docId, state.filePath);
@@ -1228,14 +2056,17 @@ function writeToDisk() {
 }
 export function save() {
     if (!state.filePath) {
-        // First save — assign a file path
+        // First save — assign a file path. Canonicalize at this identity
+        // boundary so cache lookups and watcher subscriptions key on the
+        // same string regardless of how this path was produced.
+        // adr: adr/path-canonicalization.md
         ensureDataDir();
         if (state.title === 'Untitled') {
-            state.filePath = tempFilePath();
+            state.filePath = canonicalizePath(tempFilePath());
             state.isTemp = true;
         }
         else {
-            state.filePath = filePathForTitle(state.title);
+            state.filePath = canonicalizePath(filePathForTitle(state.title));
             state.isTemp = false;
         }
     }
@@ -1243,6 +2074,9 @@ export function save() {
 }
 export function load() {
     ensureDataDir();
+    // One-time sidecar repair MUST run before any doc loads so the file-walk
+    // loop reads deduped sidecars, not corrupted ones. adr: adr/pending-overlay-model.md
+    repairOverlaysOnStartup();
     // Restore external document registry from disk
     loadExternalDocs();
     // Migrate any .sw.json files to .md
@@ -1268,19 +2102,38 @@ export function load() {
             // Skip empty temp files — prefer a real document
             if (isTemp && isDocEmpty(parsed.document))
                 continue;
-            state.document = parsed.document;
+            // Route the parsed doc through the primary-state setter — splits into
+            // canonical + overlay (handles legacy in-frontmatter pending) and
+            // recomputes the merged view via state.document.
+            setPrimaryFromMerged(parsed.document);
             state.title = parsed.title;
             state.metadata = parsed.metadata;
+            // Legacy: strip any pre-architectural-fix `agentCreated` field that
+            // survived on disk. The in-memory stub registry is the only authority.
+            stripLegacyAgentCreated(state.metadata);
             state.lastModified = new Date(statSync(file.path).mtimeMs);
-            state.filePath = file.path;
+            state.filePath = canonicalizePath(file.path);
             state.isTemp = isTemp;
+            state.loadedMtime = statSync(file.path).mtimeMs;
             // Lazy docId migration: assign if missing, save to persist
             const hadDocId = !!state.metadata.docId;
             state.docId = ensureDocId(state.metadata);
             if (!hadDocId) {
                 const md = tiptapToMarkdown(state.document, state.title, state.metadata);
                 atomicWriteFileSync(state.filePath, md);
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
             }
+            // Pending overlay merge: rehydrate pending decorations from the sidecar.
+            // For legacy files (parser stamped pending attrs from old `meta.pending`),
+            // capture those into the overlay format and write the sidecar as a one-
+            // time migration. For migrated files (parser stamped nothing because
+            // `meta.pending` is gone from frontmatter), the sidecar is the only
+            // source.
+            // adr: adr/pending-overlay-model.md
+            mergeOverlayOnLoad();
             break;
         }
         catch {
@@ -1290,15 +2143,18 @@ export function load() {
     }
     // If nothing loaded (all files were empty temps or corrupt), start fresh
     if (!state.filePath) {
-        state.filePath = tempFilePath();
+        state.filePath = canonicalizePath(tempFilePath());
         state.isTemp = true;
     }
     // Populate pending doc cache from disk (single scan on startup)
     populatePendingCache();
     // Overlay active doc's in-memory state (may have unsaved pending changes)
     updatePendingCacheForActiveDoc();
+    // Subscribe the active-doc watcher so external writes route through the
+    // unified reload pathway. adr: adr/active-doc-watcher.md
+    startActiveDocWatcher();
     // Startup lock: block browser doc-updates briefly to prevent stale reconnect pushes
-    setAgentLock();
+    setAgentLockGlobal();
 }
 /** Migrate legacy .sw.json files to .md format */
 function migrateSwJsonFiles() {
@@ -1388,9 +2244,13 @@ function cleanupEmptyTempFiles() {
             try {
                 const raw = readFileSync(fullPath, 'utf-8');
                 const parsed = markdownToTiptap(raw);
-                // Keep temp files that have meaningful metadata (templates, pending changes, tags)
+                // Keep temp files that have meaningful metadata (templates, pending changes, tags).
+                // Note: `agentCreated` used to be a disk-frontmatter signal here. Stub status is now
+                // in-memory only — see agentStubFilenames. An empty temp file with no other meaningful
+                // metadata that survived a server restart is by definition no longer a fresh stub and
+                // can be cleaned up.
                 const meta = parsed.metadata || {};
-                const hasMetadata = meta.tweetContext || meta.articleContext || meta.pending || meta.agentCreated
+                const hasMetadata = meta.tweetContext || meta.articleContext || meta.pending
                     || (Array.isArray(meta.tags) && meta.tags.length > 0);
                 if (isDocEmpty(parsed.document) && !hasMetadata) {
                     unlinkSync(fullPath);
@@ -1540,6 +2400,13 @@ export function removeDocTag(filename, tag) {
 /**
  * Save a browser doc-update to a specific file on disk.
  * Used when the browser sends a doc-update for a non-active document (race condition guard).
+ *
+ * Disk gets canonical (pending stripped by serialization). Any pending attrs
+ * carried on `doc` (transferred from disk) are persisted to the overlay
+ * sidecar in the same pass. Without the symmetric overlay save, pending
+ * content would vanish silently between the strip-during-serialize and the
+ * disk write.
+ * adr: adr/pending-overlay-model.md
  */
 export function saveDocToFile(filename, doc) {
     const targetPath = resolveDocPath(filename);
@@ -1563,6 +2430,11 @@ export function saveDocToFile(filename, doc) {
             markdown = tiptapToMarkdown(doc, parsed.title, parsed.metadata);
         }
         atomicWriteFileSync(targetPath, markdown);
+        const docId = (parsed.metadata && typeof parsed.metadata.docId === 'string') ? parsed.metadata.docId : '';
+        if (docId) {
+            const overlay = extractOverlay(doc);
+            saveOverlay(docId, overlay);
+        }
     }
     catch { /* best-effort */ }
 }
@@ -1597,9 +2469,15 @@ export function setAutoAcceptOnFile(filename, enabled) {
 }
 /**
  * Strip pending attrs from a specific file on disk (not the active document).
- * Optionally clears agentCreated metadata (on accept).
+ *
+ * The `_legacyClearAgentCreated` parameter is preserved for callsite-signature
+ * stability but no longer does anything meaningful. Stub status is in-memory
+ * only — there is no `agentCreated` field to clear on disk. The on-load
+ * legacy-strip handles any residual occurrences from pre-architectural-fix
+ * files.
+ * adr: adr/agent-stub-model.md
  */
-export function stripPendingAttrsFromFile(filename, clearAgentCreated) {
+export function stripPendingAttrsFromFile(filename, _legacyClearAgentCreated) {
     const targetPath = resolveDocPath(filename);
     if (!existsSync(targetPath))
         return;
@@ -1621,9 +2499,9 @@ export function stripPendingAttrsFromFile(filename, clearAgentCreated) {
             }
         }
         strip(parsed.document.content);
-        if (clearAgentCreated && parsed.metadata.agentCreated) {
-            delete parsed.metadata.agentCreated;
-        }
+        // Belt-and-suspenders: strip any legacy on-disk agentCreated (e.g. an
+        // old file that hasn't been re-saved since the migration).
+        stripLegacyAgentCreated(parsed.metadata);
         let markdown;
         if (isExternalDoc(targetPath)) {
             const body = tiptapToBody(parsed.document);
@@ -1635,6 +2513,12 @@ export function stripPendingAttrsFromFile(filename, clearAgentCreated) {
             markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
         }
         atomicWriteFileSync(targetPath, markdown);
+        // Pending was just cleared on disk; the sidecar overlay must go too,
+        // otherwise the next load would re-apply stale pending entries.
+        // adr: adr/pending-overlay-model.md
+        const docId = (parsed.metadata && typeof parsed.metadata.docId === 'string') ? parsed.metadata.docId : '';
+        if (docId)
+            deleteOverlay(docId);
         removePendingCacheEntry(filename);
     }
     catch { /* best-effort */ }
@@ -1658,10 +2542,25 @@ export function countPending(nodes) {
     return count;
 }
 /** Write a mutated doc back to disk and update the pending cache. */
+/** Write a mutated doc back to disk and update the pending cache.
+ *
+ *  Disk gets canonical (pending stripped by `tiptapToMarkdown`). The
+ *  overlay sidecar gets the extracted pending entries — without this,
+ *  any pending content on `doc` vanishes between strip and disk write.
+ *  This mirrors writeToDisk's active-doc path; the foundation commit
+ *  established the contract there but missed this non-active-doc
+ *  callsite. Without symmetric overlay save, populate_document /
+ *  write_to_pad on a non-active doc silently dropped pending content.
+ *  adr: adr/pending-overlay-model.md */
 function flushDocToFile(filename, doc, title, metadata) {
     const targetPath = resolveDocPath(filename);
     const markdown = tiptapToMarkdown(doc, title, metadata);
     atomicWriteFileSync(targetPath, markdown);
+    const docId = (metadata && typeof metadata.docId === 'string') ? metadata.docId : '';
+    if (docId) {
+        const overlay = extractOverlay(doc);
+        saveOverlay(docId, overlay);
+    }
     setPendingCacheEntry(filename, countPending(doc.content));
 }
 export function populateDocumentFile(filename, doc) {
@@ -1762,8 +2661,12 @@ export function applyTextEditsToFile(filename, nodeId, edits) {
         return { success: false, error: `Node ${nodeId} not found` };
     const originalNode = found.parent[found.index];
     const result = applyTextEditsToNode(originalNode, edits);
-    if (!result)
-        return { success: false, error: 'No edits matched' };
+    if (!result) {
+        const nodeText = extractText(originalNode.content || []);
+        const truncated = nodeText.length > 240 ? nodeText.slice(0, 240) + '…' : nodeText;
+        const searched = edits.map((e) => JSON.stringify(e.find)).join(', ');
+        return { success: false, error: `No edits matched in node ${nodeId}. Searched: ${searched}. Node text starts: ${JSON.stringify(truncated)}` };
+    }
     const autoAccept = isAutoAcceptActive(filename, metadata);
     // pendingTextEdits is the fine-grained inline-edit decoration — skip in autoAccept
     // since the change commits directly.