openwriter 0.2.2 → 0.3.1

package/dist/server/mcp.js

@@ -3,16 +3,23 @@
  * Uses compact wire format for token efficiency.
  * Exports TOOL_REGISTRY for HTTP proxy (multi-session support).
  */
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { randomUUID } from 'crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, getMetadata, setMetadata, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, } from './state.js';
+import { DATA_DIR, ensureDataDir } from './helpers.js';
+import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, getMetadata, setMetadata, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, updatePendingCacheForActiveDoc, getDocId, getFilePath, } from './state.js';
 import { listDocuments, switchDocument, createDocument, deleteDocument, openFile, getActiveFilename } from './documents.js';
-import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished } from './ws.js';
+import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished } from './ws.js';
 import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc } from './workspaces.js';
 import { addDocTag, removeDocTag, getDocTagsByFilename } from './state.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent } from './compact.js';
+import { getUpdateInfo } from './update-check.js';
+import { listVersions, forceSnapshot, restoreVersion } from './versions.js';
+import { markdownToTiptap } from './markdown.js';
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
@@ -44,7 +51,7 @@ export const TOOL_REGISTRY = [
                 return resolved;
             });
             const { count: appliedCount, lastNodeId } = applyChanges(processed);
-            broadcastPendingDocsChanged();
+            // broadcastPendingDocsChanged() already fires via onChanges listener in ws.ts
             return {
                 content: [{
                         type: 'text',
@@ -63,7 +70,10 @@ export const TOOL_REGISTRY = [
         description: 'Get the current status of the pad: word count, pending changes. Cheap call for polling.',
         schema: {},
         handler: async () => {
-            return { content: [{ type: 'text', text: JSON.stringify(getStatus()) }] };
+            const status = getStatus();
+            const latestVersion = getUpdateInfo();
+            const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
+            return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
         },
     },
     {
@@ -106,14 +116,15 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'create_document',
-        description: 'Create a new empty document and switch to it. Always provide a title. Saves the current document first. Shows a sidebar spinner that persists until populate_document is called — always call populate_document next to add content. If workspace is provided, the doc is automatically added to it (workspace is created if it doesn\'t exist). If container is also provided, the doc is placed inside that container (created if it doesn\'t exist).',
+        description: 'Create a new empty document and switch to it. Always provide a title. Saves the current document first. By default shows a sidebar spinner that persists until populate_document is called — set empty=true to skip the spinner and switch immediately (use for template docs like tweets/articles that don\'t need agent content). If workspace is provided, the doc is automatically added to it (workspace is created if it doesn\'t exist). If container is also provided, the doc is placed inside that container (created if it doesn\'t exist).',
         schema: {
             title: z.string().optional().describe('Title for the new document. Defaults to "Untitled".'),
             path: z.string().optional().describe('Absolute file path to create the document at (e.g. "C:/projects/doc.md"). If omitted, creates in ~/.openwriter/.'),
             workspace: z.string().optional().describe('Workspace title to add this doc to. Creates the workspace if it doesn\'t exist.'),
             container: z.string().optional().describe('Container name within the workspace (e.g. "Chapters", "Notes", "References"). Creates the container if it doesn\'t exist. Requires workspace.'),
+            empty: z.boolean().optional().describe('If true, skip the writing spinner and switch to the doc immediately. No need to call populate_document. Use for template docs (tweets, articles) that start empty.'),
         },
-        handler: async ({ title, path, workspace, container }) => {
+        handler: async ({ title, path, workspace, container, empty }) => {
             // Resolve workspace/container up front so spinner renders in the right place
             let wsTarget;
             if (workspace) {
@@ -126,24 +137,40 @@ export const TOOL_REGISTRY = [
                 wsTarget = { wsFilename: ws.filename, containerId };
                 broadcastWorkspacesChanged(); // Browser sees container structure before spinner
             }
-            broadcastWritingStarted(title || 'Untitled', wsTarget);
-            // Yield so the browser receives and renders the placeholder before heavy work
-            await new Promise((resolve) => setTimeout(resolve, 200));
+            if (!empty) {
+                broadcastWritingStarted(title || 'Untitled', wsTarget);
+                // Yield so the browser receives and renders the spinner before heavy work
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
             try {
                 // Lock browser doc-updates: prevents race where browser sends a doc-update
                 // for the previous document but server has already switched active doc.
                 setAgentLock();
                 const result = createDocument(title, undefined, path);
-                setMetadata({ agentCreated: true });
-                save(); // Persist agentCreated flag to frontmatter
-                // Auto-add to workspace if specified (defer sidebar broadcasts to populate_document
-                // so the real doc entry doesn't appear alongside the spinner placeholder)
+                // Auto-add to workspace if specified
                 let wsInfo = '';
                 if (wsTarget) {
                     addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
                     wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                 }
-                // Spinner persists until populate_document is called
+                if (empty) {
+                    // Immediate switch — no spinner, no populate_document needed
+                    save();
+                    broadcastDocumentsChanged();
+                    broadcastWorkspacesChanged();
+                    broadcastDocumentSwitched(getDocument(), getTitle(), getActiveFilename());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Created "${result.title}" (${result.filename})${wsInfo} — ready.`,
+                            }],
+                    };
+                }
+                // Two-step flow: spinner persists until populate_document is called
+                setMetadata({ agentCreated: true });
+                save(); // Persist agentCreated flag to frontmatter
+                broadcastDocumentsChanged();
+                broadcastDocumentSwitched(getDocument(), getTitle(), getActiveFilename());
                 return {
                     content: [{
                             type: 'text',
@@ -152,7 +179,8 @@ export const TOOL_REGISTRY = [
                 };
             }
             catch (err) {
-                broadcastWritingFinished();
+                if (!empty)
+                    broadcastWritingFinished();
                 throw err;
             }
         },
@@ -181,6 +209,7 @@ export const TOOL_REGISTRY = [
                 setAgentLock(); // Block browser doc-updates during population
                 markAllNodesAsPending(doc, 'insert');
                 updateDocument(doc);
+                updatePendingCacheForActiveDoc();
                 save();
                 // Broadcast sidebar updates first (deferred from create_document) so the doc
                 // entry and spinner removal arrive in the same render cycle
@@ -270,6 +299,7 @@ export const TOOL_REGISTRY = [
             for (const key of removed)
                 delete meta[key];
             save();
+            broadcastMetadataChanged(getMetadata());
             if (cleaned.title) {
                 broadcastTitleChanged(cleaned.title);
                 broadcastDocumentsChanged();
@@ -475,10 +505,10 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'import_gdoc',
-        description: 'Import a Google Doc into OpenWriter. Accepts raw Google Doc JSON (from Google Docs API). If the doc has multiple HEADING_1 sections, splits into chapter files and creates a book manifest. Otherwise imports as a single document.',
+        description: 'Import a structured Google Doc into OpenWriter. Pass the raw JSON from the Google Docs API (the object with body.content). Converts headings, bold/italic, links, lists, and tables to markdown. Docs with 2+ HEADING_1 sections auto-split into chapter files with a workspace and "Chapters" container. Single-section docs become one file.',
         schema: {
-            document: z.any().describe('Raw Google Doc JSON object (must have body.content)'),
-            title: z.string().optional().describe('Book title. Defaults to the Google Doc title.'),
+            document: z.any().describe('Raw Google Doc JSON object from the Docs API (must have body.content)'),
+            title: z.string().optional().describe('Book/document title. Defaults to the Google Doc title.'),
         },
         handler: async ({ document, title }) => {
             const result = importGoogleDoc(document, title);
@@ -492,8 +522,141 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text }] };
         },
     },
+    {
+        name: 'generate_image',
+        description: 'Generate an image using Gemini Imagen 4. Saves to ~/.openwriter/_images/. Optionally sets it as the active article\'s cover image atomically. Requires GEMINI_API_KEY env var.',
+        schema: {
+            prompt: z.string().max(1000).describe('Image generation prompt (max 1000 chars)'),
+            aspect_ratio: z.string().optional().describe('Aspect ratio (default "16:9"). Supported: 1:1, 9:16, 16:9, 4:3, 3:4.'),
+            set_cover: z.boolean().optional().describe('If true, atomically set the generated image as the article cover (articleContext.coverImage in metadata).'),
+        },
+        handler: async ({ prompt, aspect_ratio, set_cover }) => {
+            const apiKey = process.env.GEMINI_API_KEY;
+            if (!apiKey) {
+                return { content: [{ type: 'text', text: 'Error: GEMINI_API_KEY environment variable is not set.' }] };
+            }
+            const { GoogleGenAI } = await import('@google/genai');
+            const ai = new GoogleGenAI({ apiKey });
+            const response = await ai.models.generateImages({
+                model: 'imagen-4.0-generate-001',
+                prompt,
+                config: {
+                    numberOfImages: 1,
+                    aspectRatio: (aspect_ratio || '16:9'),
+                },
+            });
+            const image = response.generatedImages?.[0];
+            if (!image?.image?.imageBytes) {
+                return { content: [{ type: 'text', text: 'Error: Gemini returned no image data.' }] };
+            }
+            // Save to ~/.openwriter/_images/
+            ensureDataDir();
+            const imagesDir = join(DATA_DIR, '_images');
+            if (!existsSync(imagesDir))
+                mkdirSync(imagesDir, { recursive: true });
+            const filename = `${randomUUID().slice(0, 8)}.png`;
+            const filePath = join(imagesDir, filename);
+            writeFileSync(filePath, Buffer.from(image.image.imageBytes, 'base64'));
+            const src = `/_images/${filename}`;
+            // Optionally set as article cover + append to carousel history
+            if (set_cover) {
+                const meta = getMetadata();
+                const articleContext = meta.articleContext || {};
+                let existing = Array.isArray(articleContext.coverImages) ? articleContext.coverImages : [];
+                // Seed with current coverImage if array is empty (first carousel entry)
+                if (existing.length === 0 && articleContext.coverImage) {
+                    existing = [articleContext.coverImage];
+                }
+                existing.push(src);
+                articleContext.coverImage = src;
+                articleContext.coverImages = existing;
+                setMetadata({ articleContext });
+                save();
+                broadcastMetadataChanged(getMetadata());
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: true, src, ...(set_cover ? { coverSet: true } : {}) }),
+                    }],
+            };
+        },
+    },
+    {
+        name: 'list_versions',
+        description: 'List version history for the active document. Returns timestamps, word counts, and sizes. Use to find a timestamp for restore_version.',
+        schema: {},
+        handler: async () => {
+            const docId = getDocId();
+            if (!docId)
+                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
+            const versions = listVersions(docId);
+            if (versions.length === 0)
+                return { content: [{ type: 'text', text: 'No versions found for this document.' }] };
+            const lines = versions.map((v, i) => `  ${i + 1}. ${v.date}  ts:${v.timestamp}  ${v.wordCount.toLocaleString()} words  ${(v.size / 1024).toFixed(1)}KB`);
+            return { content: [{ type: 'text', text: `versions (${versions.length}):\n${lines.join('\n')}` }] };
+        },
+    },
+    {
+        name: 'create_checkpoint',
+        description: 'Force a version snapshot of the active document right now. Use before risky operations as a safety net.',
+        schema: {},
+        handler: async () => {
+            const docId = getDocId();
+            const filePath = getFilePath();
+            if (!docId || !filePath)
+                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
+            forceSnapshot(docId, filePath);
+            return { content: [{ type: 'text', text: `Checkpoint created at ${new Date().toISOString()}` }] };
+        },
+    },
+    {
+        name: 'restore_version',
+        description: 'Restore the active document to a previous version by timestamp. Automatically creates a safety checkpoint of the current state first. Get timestamps from list_versions.',
+        schema: {
+            timestamp: z.number().describe('Version timestamp to restore (from list_versions)'),
+        },
+        handler: async ({ timestamp }) => {
+            const docId = getDocId();
+            const filePath = getFilePath();
+            if (!docId || !filePath)
+                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
+            // Safety net: snapshot current state before restoring
+            try {
+                forceSnapshot(docId, filePath);
+            }
+            catch { /* best effort */ }
+            const parsed = restoreVersion(docId, timestamp);
+            if (!parsed)
+                return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
+            updateDocument(parsed.document);
+            save();
+            const filename = filePath.split(/[/\\]/).pop() || '';
+            broadcastDocumentSwitched(parsed.document, parsed.title, filename);
+            return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()} — "${parsed.title}"` }] };
+        },
+    },
+    {
+        name: 'reload_from_disk',
+        description: 'Re-read the active document from its file on disk. Use when the file was modified externally and the editor needs to pick up changes. Does NOT rescan the full document list.',
+        schema: {},
+        handler: async () => {
+            const filePath = getFilePath();
+            if (!filePath)
+                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
+            if (!existsSync(filePath))
+                return { content: [{ type: 'text', text: `Error: File not found: ${filePath}` }] };
+            const markdown = readFileSync(filePath, 'utf-8');
+            const parsed = markdownToTiptap(markdown);
+            updateDocument(parsed.document);
+            save();
+            const filename = filePath.split(/[/\\]/).pop() || '';
+            broadcastDocumentSwitched(parsed.document, parsed.title, filename);
+            return { content: [{ type: 'text', text: `Reloaded "${parsed.title}" from disk` }] };
+        },
+    },
 ];
-/** Register MCP tools from plugins. Call before startMcpServer(). */
+/** Register MCP tools from plugins. Tools added after startMcpServer() won't be visible to existing MCP sessions. */
 export function registerPluginTools(tools) {
     for (const tool of tools) {
         TOOL_REGISTRY.push({
@@ -518,7 +681,7 @@ export function removePluginTools(names) {
 }
 export async function startMcpServer() {
     const server = new McpServer({
-        name: 'open-writer',
+        name: 'openwriter',
         version: '0.2.0',
     });
     for (const tool of TOOL_REGISTRY) {

package/dist/server/state.js

@@ -143,6 +143,22 @@ export function setMetadata(updates) {
     state.metadata = { ...state.metadata, ...updates };
     if (updates.title)
         state.title = updates.title;
+    // Auto-tag: tweetContext / articleContext ↔ "x" tag
+    for (const key of ['tweetContext', 'articleContext']) {
+        if (key in updates) {
+            const filename = state.filePath
+                ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
+                : '';
+            if (filename) {
+                if (updates[key]) {
+                    addDocTag(filename, 'x');
+                }
+                else {
+                    removeDocTag(filename, 'x');
+                }
+            }
+        }
+    }
 }
 export function getStatus() {
     return {
@@ -210,7 +226,7 @@ function transferPendingAttrs(source, target) {
 // ============================================================================
 // AGENT WRITE LOCK
 // ============================================================================
-const AGENT_LOCK_MS = 5000; // Block browser doc-updates for 5s after agent write
+const AGENT_LOCK_MS = 1500; // Block browser doc-updates for 1.5s after agent write
 let lastAgentWriteTime = 0;
 /** Set the agent write lock (called after agent changes). */
 export function setAgentLock() {
@@ -249,6 +265,8 @@ export function applyChanges(changes) {
     }
     // Debounced save — coalesces rapid agent writes into a single disk write
     debouncedSave();
+    // Update pending doc cache for the active document
+    updatePendingCacheForActiveDoc();
     // Find the last created node ID for chaining inserts
     let lastNodeId = null;
     for (let i = processed.length - 1; i >= 0; i--) {
@@ -309,7 +327,7 @@ function applyChangesToDocument(changes) {
             if (!found)
                 continue;
             const contentArray = Array.isArray(change.content) ? change.content : [change.content];
-            const originalNode = JSON.parse(JSON.stringify(found.parent[found.index]));
+            const originalNode = structuredClone(found.parent[found.index]);
             // Only store original on first rewrite (preserve baseline for reject)
             const existingOriginal = found.parent[found.index].attrs?.pendingOriginalContent;
             // First node replaces the target (rewrite)
@@ -426,6 +444,65 @@ export function setActiveDocument(doc, title, filePath, isTemp, lastModified, me
     state.docId = ensureDocId(state.metadata);
 }
 // ============================================================================
+// PENDING DOCUMENT CACHE (avoids disk scans on every broadcast)
+// ============================================================================
+/** In-memory cache: filename → pending change count. Populated on load(), updated incrementally. */
+const pendingDocCache = new Map();
+/** Get the active doc's filename identifier (mirrors getActiveFilename in documents.ts). */
+function activeDocFilename() {
+    return state.filePath
+        ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
+        : '';
+}
+/** Update the pending cache for the active document from in-memory state. */
+export function updatePendingCacheForActiveDoc() {
+    const filename = activeDocFilename();
+    if (!filename)
+        return;
+    const count = getPendingChangeCount();
+    if (count > 0) {
+        pendingDocCache.set(filename, count);
+    }
+    else {
+        pendingDocCache.delete(filename);
+    }
+}
+/** Remove a filename from the pending cache (after pending attrs are stripped). */
+export function removePendingCacheEntry(filename) {
+    pendingDocCache.delete(filename);
+}
+/** Populate the pending cache from a full disk scan. Called once on startup. */
+function populatePendingCache() {
+    pendingDocCache.clear();
+    try {
+        const files = readdirSync(DATA_DIR).filter((f) => f.endsWith('.md'));
+        for (const f of files) {
+            try {
+                const raw = readFileSync(join(DATA_DIR, f), 'utf-8');
+                const { data } = matter(raw);
+                if (data.pending && Object.keys(data.pending).length > 0) {
+                    pendingDocCache.set(f, Object.keys(data.pending).length);
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+    }
+    catch { /* ignore */ }
+    // Scan external docs
+    for (const extPath of externalDocs) {
+        try {
+            if (!existsSync(extPath))
+                continue;
+            const raw = readFileSync(extPath, 'utf-8');
+            const { data } = matter(raw);
+            if (data.pending && Object.keys(data.pending).length > 0) {
+                pendingDocCache.set(extPath, Object.keys(data.pending).length);
+            }
+        }
+        catch { /* skip unreadable files */ }
+    }
+}
+// ============================================================================
 // PENDING DOCUMENT STORE OPERATIONS
 // ============================================================================
 /** Check if a document (or the current doc) has any pending changes. */
@@ -460,6 +537,7 @@ export function stripPendingAttrs() {
         }
     }
     strip(state.document.content);
+    removePendingCacheEntry(activeDocFilename());
 }
 /**
  * Mark leaf block nodes as pending within a node array.
@@ -485,83 +563,15 @@ function markLeafBlocksAsPending(nodes, status) {
 export function markAllNodesAsPending(doc, status) {
     markLeafBlocksAsPending(doc.content, status);
 }
-/** Get filenames of all docs with pending changes (disk scan + external docs + current in-memory doc). */
-export function getPendingDocFilenames() {
+/** Read pending doc info from in-memory cache (O(1) instead of disk scan). */
+export function getPendingDocInfo() {
     const filenames = [];
-    try {
-        const files = readdirSync(DATA_DIR).filter((f) => f.endsWith('.md'));
-        for (const f of files) {
-            try {
-                const raw = readFileSync(join(DATA_DIR, f), 'utf-8');
-                const { data } = matter(raw);
-                if (data.pending && Object.keys(data.pending).length > 0) {
-                    filenames.push(f);
-                }
-            }
-            catch { /* skip unreadable files */ }
-        }
-    }
-    catch { /* ignore */ }
-    // Scan external docs for pending frontmatter
-    for (const extPath of externalDocs) {
-        try {
-            if (!existsSync(extPath))
-                continue;
-            const raw = readFileSync(extPath, 'utf-8');
-            const { data } = matter(raw);
-            if (data.pending && Object.keys(data.pending).length > 0) {
-                filenames.push(extPath);
-            }
-        }
-        catch { /* skip unreadable files */ }
-    }
-    // Check current in-memory doc (may have unsaved pending state)
-    const currentFilename = state.filePath
-        ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
-        : '';
-    if (currentFilename && hasPendingChanges() && !filenames.includes(currentFilename)) {
-        filenames.push(currentFilename);
-    }
-    return filenames;
-}
-/** Get pending change counts per filename (disk scan + external docs + current in-memory doc). */
-export function getPendingDocCounts() {
     const counts = {};
-    try {
-        const files = readdirSync(DATA_DIR).filter((f) => f.endsWith('.md'));
-        for (const f of files) {
-            try {
-                const raw = readFileSync(join(DATA_DIR, f), 'utf-8');
-                const { data } = matter(raw);
-                if (data.pending && Object.keys(data.pending).length > 0) {
-                    counts[f] = Object.keys(data.pending).length;
-                }
-            }
-            catch { /* skip unreadable files */ }
-        }
+    for (const [filename, count] of pendingDocCache) {
+        filenames.push(filename);
+        counts[filename] = count;
     }
-    catch { /* ignore */ }
-    // Scan external docs
-    for (const extPath of externalDocs) {
-        try {
-            if (!existsSync(extPath))
-                continue;
-            const raw = readFileSync(extPath, 'utf-8');
-            const { data } = matter(raw);
-            if (data.pending && Object.keys(data.pending).length > 0) {
-                counts[extPath] = Object.keys(data.pending).length;
-            }
-        }
-        catch { /* skip unreadable files */ }
-    }
-    // Current in-memory doc may have unsaved pending state
-    const currentFilename = state.filePath
-        ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
-        : '';
-    if (currentFilename && hasPendingChanges()) {
-        counts[currentFilename] = getPendingChangeCount();
-    }
-    return counts;
+    return { filenames, counts };
 }
 // ============================================================================
 // PERSISTENCE
@@ -630,36 +640,45 @@ export function load() {
         return { name: f, path: fullPath, mtime: stat.mtimeMs };
     })
         .sort((a, b) => b.mtime - a.mtime);
-    if (files.length === 0) {
-        // No existing docs — start fresh with temp file
-        state.filePath = tempFilePath();
-        state.isTemp = true;
-        return;
-    }
-    // Open the most recent file
-    const latest = files[0];
-    try {
-        const raw = readFileSync(latest.path, 'utf-8');
-        const parsed = markdownToTiptap(raw);
-        state.document = parsed.document;
-        state.title = parsed.title;
-        state.metadata = parsed.metadata;
-        state.lastModified = new Date(statSync(latest.path).mtimeMs);
-        state.filePath = latest.path;
-        state.isTemp = latest.name.startsWith(TEMP_PREFIX);
-        // 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);
-            writeFileSync(state.filePath, md, 'utf-8');
+    // Walk sorted files until we find a real document with content.
+    // Skip empty temp files so we don't open a blank scratch pad when real docs exist.
+    for (const file of files) {
+        try {
+            const raw = readFileSync(file.path, 'utf-8');
+            const parsed = markdownToTiptap(raw);
+            const isTemp = file.name.startsWith(TEMP_PREFIX);
+            // Skip empty temp files — prefer a real document
+            if (isTemp && isDocEmpty(parsed.document))
+                continue;
+            state.document = parsed.document;
+            state.title = parsed.title;
+            state.metadata = parsed.metadata;
+            state.lastModified = new Date(statSync(file.path).mtimeMs);
+            state.filePath = file.path;
+            state.isTemp = isTemp;
+            // 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);
+                writeFileSync(state.filePath, md, 'utf-8');
+            }
+            break;
+        }
+        catch {
+            // Corrupt file — try next one
+            continue;
         }
     }
-    catch {
-        // Corrupt file — start fresh
+    // If nothing loaded (all files were empty temps or corrupt), start fresh
+    if (!state.filePath) {
         state.filePath = 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();
     // Startup lock: block browser doc-updates briefly to prevent stale reconnect pushes
     setAgentLock();
 }
@@ -915,6 +934,7 @@ export function stripPendingAttrsFromFile(filename, clearAgentCreated) {
         }
         const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
         writeFileSync(targetPath, markdown, 'utf-8');
+        removePendingCacheEntry(filename);
     }
     catch { /* best-effort */ }
 }