nebula-notebook 0.1.0 → 0.2.0

package/node-server/dist/notebook/cell-hash.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Content hash for optimistic concurrency control on agent writes.
+ *
+ * The operation router records the hash of each cell's content as the agent
+ * last saw it (from read results); write operations carry that hash and the
+ * applier — the live UI when connected, the headless handler otherwise —
+ * rejects the write if the cell's current content no longer matches. This is
+ * compare-and-swap at the point of application: immune to autosave latency
+ * and to browser/server clock skew (which rule out timestamp-based checks).
+ *
+ * MUST stay in sync with lib/cellHash.ts (frontend copy).
+ */
+export declare function hashCellContent(content: string): string;

package/node-server/dist/notebook/cell-hash.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashCellContent = hashCellContent;
+/**
+ * Content hash for optimistic concurrency control on agent writes.
+ *
+ * The operation router records the hash of each cell's content as the agent
+ * last saw it (from read results); write operations carry that hash and the
+ * applier — the live UI when connected, the headless handler otherwise —
+ * rejects the write if the cell's current content no longer matches. This is
+ * compare-and-swap at the point of application: immune to autosave latency
+ * and to browser/server clock skew (which rule out timestamp-based checks).
+ *
+ * MUST stay in sync with lib/cellHash.ts (frontend copy).
+ */
+function hashCellContent(content) {
+    // FNV-1a, 32-bit, hex — stable, fast, and tiny. Collisions are acceptable:
+    // a false "unchanged" requires an adversarial collision; the cost of a
+    // false conflict is one extra agent read.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < content.length; i++) {
+        hash ^= content.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}

package/node-server/dist/notebook/headless-handler.d.ts

@@ -52,6 +52,8 @@ export declare class HeadlessOperationHandler {
      * Persist dirty notebooks to disk.
      */
     flush(notebookPath?: string): Promise<void>;
+    /** In-flight persist per notebook path (single-flight). */
+    private persisting;
     private asyncPersist;
     private schedulePersist;
     /**
@@ -66,6 +68,13 @@ export declare class HeadlessOperationHandler {
      * Check if agent has permission to modify this notebook.
      */
     private checkAgentPermission;
+    /**
+     * Compare expectedHash/expectedHashes stamped by the operation router
+     * against current cell content. Returns a conflict result, or null to
+     * proceed. The conflict message carries the current content so the agent
+     * can re-apply its intent without an extra read.
+     */
+    private checkExpectedHashes;
     /**
      * Apply a notebook operation.
      */

package/node-server/dist/notebook/headless-handler.js

@@ -41,9 +41,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HeadlessOperationHandler = void 0;
 const fs = __importStar(require("fs"));
+const cell_hash_1 = require("./cell-hash");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const uuid_1 = require("uuid");
+const registry_1 = require("../fs/notebook-formats/registry");
 const cell_metadata_1 = require("./cell-metadata");
 const undoRedoManager_1 = require("./undoRedoManager");
 const kernelspec_1 = require("../kernel/kernelspec");
@@ -79,7 +81,7 @@ class HeadlessOperationHandler {
      */
     getCachedNotebook(notebookPath) {
         if (!this.cache.has(notebookPath)) {
-            const result = this.fsService.getNotebookCells(notebookPath);
+            const result = this.fsService.getNotebookCellsSync(notebookPath);
             this.cache.set(notebookPath, {
                 cells: result.cells || [],
                 metadata: result.metadata || {},
@@ -108,23 +110,41 @@ class HeadlessOperationHandler {
     async flush(notebookPath) {
         const paths = notebookPath ? [notebookPath] : Array.from(this.cache.keys());
         for (const p of paths) {
-            const notebook = this.cache.get(p);
-            if (notebook?.dirty) {
+            // A scheduled persist may have already cleared the dirty flag but not
+            // finished writing — flush must wait for it, or callers read a stale
+            // file. The persist loop keeps writing while dirty, so awaiting the
+            // in-flight run covers later mutations too.
+            const inFlight = this.persisting.get(p);
+            if (inFlight) {
+                await inFlight;
+            }
+            if (this.cache.get(p)?.dirty) {
                 await this.asyncPersist(p);
             }
         }
     }
-    async asyncPersist(notebookPath) {
-        const notebook = this.cache.get(notebookPath);
-        if (!notebook)
-            return;
-        // Keep writing while dirty
-        while (notebook.dirty) {
-            const cells = JSON.parse(JSON.stringify(notebook.cells));
-            notebook.dirty = false;
-            const history = this.undoRedoManager.getHistory(notebookPath, cells);
-            await this.fsService.saveNotebookBundle(notebookPath, cells, undefined, history);
-        }
+    /** In-flight persist per notebook path (single-flight). */
+    persisting = new Map();
+    asyncPersist(notebookPath) {
+        const existing = this.persisting.get(notebookPath);
+        if (existing)
+            return existing;
+        const run = (async () => {
+            const notebook = this.cache.get(notebookPath);
+            if (!notebook)
+                return;
+            // Keep writing while dirty
+            while (notebook.dirty) {
+                const cells = JSON.parse(JSON.stringify(notebook.cells));
+                notebook.dirty = false;
+                const history = this.undoRedoManager.getHistory(notebookPath, cells);
+                await this.fsService.saveNotebookBundle(notebookPath, cells, undefined, history);
+            }
+        })().finally(() => {
+            this.persisting.delete(notebookPath);
+        });
+        this.persisting.set(notebookPath, run);
+        return run;
     }
     schedulePersist(notebookPath) {
         // Schedule async persist
@@ -142,6 +162,10 @@ class HeadlessOperationHandler {
         else {
             this.cache.clear();
         }
+        // Undo/redo state is derived from the persisted history file; when the
+        // notebook may have changed underneath us (UI save, external edit
+        // reconciliation), rebuild it from disk on next access.
+        this.undoRedoManager.clearState(notebookPath);
     }
     /**
      * Check if notebook has unsaved changes.
@@ -154,22 +178,70 @@ class HeadlessOperationHandler {
      */
     checkAgentPermission(notebookPath, _operationType) {
         const status = this.fsService.getAgentPermissionStatus(notebookPath);
-        if (status.agent_created) {
+        // can_agent_modify already encodes the tri-state rule (agent-created notebooks
+        // are permitted unless explicitly revoked; user notebooks need permission +
+        // history), so an explicit user revoke wins even for agent-created notebooks.
+        if (status.can_agent_modify) {
+            return null;
+        }
+        // User-permitted but history not yet enabled (soft, fixable) vs. not permitted.
+        if (status.agent_permitted && !status.has_history && !status.agent_created) {
+            return {
+                success: false,
+                error: `Agent cannot modify "${notebookPath}": notebook is user-permitted but history is not enabled. Open the notebook in the UI first to enable history tracking, or the agent can create a new notebook.`,
+            };
+        }
+        return {
+            success: false,
+            error: `Agent cannot modify "${notebookPath}": notebook is not agent-permitted (agent access may have been revoked). Either open the notebook in Nebula UI and grant agent permission, or the agent can create a new notebook which will be automatically permitted.`,
+        };
+    }
+    /**
+     * Compare expectedHash/expectedHashes stamped by the operation router
+     * against current cell content. Returns a conflict result, or null to
+     * proceed. The conflict message carries the current content so the agent
+     * can re-apply its intent without an extra read.
+     */
+    checkExpectedHashes(operation, notebookPath) {
+        const expectedHash = operation.expectedHash;
+        const expectedHashes = operation.expectedHashes;
+        if (!expectedHash && !expectedHashes)
+            return null;
+        if (!notebookPath)
             return null;
+        const cells = this.getCells(notebookPath);
+        const checks = [];
+        if (expectedHash && typeof operation.cellId === 'string') {
+            checks.push({ cellId: operation.cellId, expected: expectedHash });
+        }
+        if (expectedHashes) {
+            for (const [cellId, expected] of Object.entries(expectedHashes)) {
+                checks.push({ cellId, expected });
+            }
         }
-        if (status.agent_permitted) {
-            if (!status.has_history) {
+        for (const { cellId, expected } of checks) {
+            const cell = cells.find(c => c.id === cellId);
+            if (!cell) {
                 return {
                     success: false,
-                    error: `Agent cannot modify "${notebookPath}": notebook is user-permitted but history is not enabled. Open the notebook in the UI first to enable history tracking, or the agent can create a new notebook.`,
+                    conflict: true,
+                    error: `Conflict: cell ${cellId} no longer exists (it changed since you last read it). Re-read the notebook and retry.`,
+                };
+            }
+            const current = (0, cell_hash_1.hashCellContent)(cell.content ?? '');
+            if (current !== expected) {
+                const preview = (cell.content ?? '').slice(0, 2000);
+                return {
+                    success: false,
+                    conflict: true,
+                    error: `Conflict: cell ${cellId} was modified (likely by the user) after you last read it. ` +
+                        `Current content:\n${preview}${(cell.content ?? '').length > 2000 ? '\n…(truncated)' : ''}\n` +
+                        `Re-apply your intent against this content and retry — your next write to this cell is validated against the content shown above, so no re-read is needed.`,
+                    currentContent: cell.content,
                 };
             }
-            return null;
         }
-        return {
-            success: false,
-            error: `Agent cannot modify "${notebookPath}": notebook is not agent-permitted. Either open the notebook in Nebula UI and grant agent permission, or the agent can create a new notebook which will be automatically permitted.`,
-        };
+        return null;
     }
     /**
      * Apply a notebook operation.
@@ -187,6 +259,13 @@ class HeadlessOperationHandler {
                 return permissionError;
             }
         }
+        // Optimistic concurrency: collaborative agent sessions stamp destructive
+        // writes with the content hash the agent last saw (see operation-router).
+        // Verify against current content before applying.
+        const occConflict = this.checkExpectedHashes(operation, notebookPath);
+        if (occConflict) {
+            return occConflict;
+        }
         try {
             let result;
             switch (opType) {
@@ -726,6 +805,28 @@ class HeadlessOperationHandler {
                 error: `Notebook already exists: ${notebookPath}. Use overwrite=true to replace.`,
             };
         }
+        // Text notebook formats (.py percent / .qmd): create through the format
+        // adapter — agent flags live in the file's own metadata like .ipynb.
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        if (formatAdapter) {
+            const dir = path.dirname(normalizedPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const metadata = {
+                kernelspec: { name: kernelName, display_name: kernelDisplayName },
+                nebula: { agent_created: true, agent_permitted: true },
+            };
+            if (formatAdapter.name === 'qmd')
+                metadata.__qmd_language = 'python';
+            fs.writeFileSync(normalizedPath, formatAdapter.serialize([], metadata), 'utf-8');
+            this.invalidate(notebookPath);
+            return {
+                success: true,
+                path: notebookPath,
+                mtime: fs.statSync(normalizedPath).mtimeMs / 1000,
+            };
+        }
         const notebook = {
             nbformat: 4,
             nbformat_minor: 5,

package/node-server/dist/notebook/operation-router.d.ts

@@ -12,6 +12,7 @@ import { HeadlessOperationHandler } from './headless-handler';
 interface KernelChangedPayload {
     kernelName: string;
     serverId?: string | null;
+    mtime?: number;
 }
 type Backend = 'ui' | 'headless';
 interface OperationResult {
@@ -27,12 +28,15 @@ interface AgentLock {
     expiresAt: number;
     notebookPath: string;
     lockedAt: number;
+    exclusive: boolean;
+    cellHashes: Map<string, string>;
 }
 export declare class OperationRouter {
     private uiConnections;
     private headlessHandler;
     private operationTimeout;
     private agentLocks;
+    private preSessionReadHashes;
     setHeadlessHandler(handler: HeadlessOperationHandler): void;
     /**
      * Register a UI connection for a notebook path.
@@ -58,6 +62,7 @@ export declare class OperationRouter {
     startAgentSession(notebookPath: string, agentId: string, metadata?: {
         clientName?: string;
         clientVersion?: string;
+        exclusive?: boolean;
     }): {
         success: boolean;
         error?: string;
@@ -97,6 +102,37 @@ export declare class OperationRouter {
      * Apply a notebook operation.
      */
     applyOperation(operation: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * OCC preparation for a destructive write in a collaborative session.
+     * Returns an error string to reject the operation, or null to proceed
+     * (with `expectedHash`/`expectedHashes` stamped onto the operation).
+     *
+     * Policy:
+     * - updateContent / updateMetadata / deleteCell / deleteCells: the agent
+     *   must have read the cell this session (hash known), and the applier
+     *   verifies the content still matches before applying.
+     * - executeCell: verified only when the hash is known (running slightly
+     *   stale content is recoverable; destroying user edits is not).
+     * - clearNotebook: requires an exclusive session.
+     * - Index-addressed destructive writes are rejected: user edits shift
+     *   indices, so collaborative writes must address cells by id.
+     */
+    private prepareCollaborativeWrite;
+    /**
+     * Record the session's view of cell content from operation results.
+     * Keyed to the notebook's active lock: the lock guarantees a single writing
+     * agent per notebook, so reads from any source refreshing it is sound.
+     */
+    private recordSessionHashes;
+    /**
+     * Record hashes for a full-notebook read (used by router.readNotebook,
+     * which serves the MCP read_notebook tool outside applyOperation).
+     */
+    recordNotebookReadHashes(notebookPath: string, cells: Array<{
+        id?: string;
+        content?: string;
+    }>): void;
+    private getPreSessionStore;
     private forwardToUI;
     /**
      * Handle operation response from UI.

package/node-server/dist/notebook/operation-router.js

@@ -47,6 +47,8 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const ws_1 = require("ws");
+const cell_hash_1 = require("./cell-hash");
+const registry_1 = require("../fs/notebook-formats/registry");
 const AGENT_LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const UI_STALE_TIMEOUT_MS = 45 * 1000; // 45 seconds
 function normalizeNotebookPath(notebookPath) {
@@ -62,6 +64,11 @@ class OperationRouter {
     headlessHandler = null;
     operationTimeout = 30000; // 30 seconds
     agentLocks = new Map(); // path -> lock
+    // Content hashes from reads that happen OUTSIDE a session (agents read to
+    // orient themselves before calling start_agent_session). Seeds the session's
+    // cellHashes on start so the first write doesn't hit "read it first".
+    // Keyed per path — the per-notebook lock already serializes writing agents.
+    preSessionReadHashes = new Map();
     setHeadlessHandler(handler) {
         this.headlessHandler = handler;
     }
@@ -93,6 +100,11 @@ class OperationRouter {
             pendingRequests: new Map(),
             lastActivityAt: Date.now(),
         });
+        // The UI is now the source of truth for this notebook; any headless cache
+        // is potentially stale (and would be consulted again if this connection
+        // goes stale or closes).
+        this.headlessHandler?.invalidate(notebookPath);
+        this.headlessHandler?.invalidate(normalizedPath);
         console.log(`[OperationRouter] UI registered for: ${normalizedPath}`);
     }
     /**
@@ -111,6 +123,10 @@ class OperationRouter {
                 request.reject(new Error('UI disconnected'));
             }
             this.uiConnections.delete(normalizedPath);
+            // Subsequent ops route headless — make sure they reload from disk (which
+            // has the UI's autosaves) rather than a cache predating the UI session.
+            this.headlessHandler?.invalidate(notebookPath);
+            this.headlessHandler?.invalidate(normalizedPath);
             console.log(`[OperationRouter] UI unregistered for: ${normalizedPath}`);
         }
     }
@@ -125,6 +141,7 @@ class OperationRouter {
                 type: 'kernelChanged',
                 kernelName: payload.kernelName,
                 serverId: payload.serverId ?? null,
+                mtime: payload.mtime,
             }));
         }
         catch (err) {
@@ -169,8 +186,12 @@ class OperationRouter {
         const existingLock = this.agentLocks.get(normalizedPath);
         if (existingLock) {
             if (existingLock.agentId === agentId) {
-                // Same agent re-acquiring lock - refresh timeout
+                // Same agent re-acquiring lock - refresh timeout (and allow it to
+                // upgrade/downgrade exclusivity)
                 existingLock.expiresAt = Date.now() + AGENT_LOCK_TIMEOUT_MS;
+                if (metadata?.exclusive !== undefined) {
+                    existingLock.exclusive = metadata.exclusive;
+                }
                 console.log(`[OperationRouter] Agent session refreshed for: ${normalizedPath} (agent: ${agentId})`);
                 return { success: true, lock: existingLock };
             }
@@ -185,7 +206,8 @@ class OperationRouter {
                 };
             }
         }
-        // Acquire new lock
+        // Acquire new lock — seeded with hashes from any pre-session reads, so the
+        // standard orient-then-edit agent flow doesn't trip "read it first".
         const now = Date.now();
         const newLock = {
             agentId,
@@ -194,6 +216,8 @@ class OperationRouter {
             expiresAt: now + AGENT_LOCK_TIMEOUT_MS,
             notebookPath: normalizedPath,
             lockedAt: now,
+            exclusive: metadata?.exclusive === true,
+            cellHashes: new Map(this.preSessionReadHashes.get(normalizedPath) ?? []),
         };
         this.agentLocks.set(normalizedPath, newLock);
         console.log(`[OperationRouter] Agent session started for: ${normalizedPath} (agent: ${agentId}, client: ${metadata?.clientName || 'unknown'})`);
@@ -297,9 +321,13 @@ class OperationRouter {
         const opType = operation.type;
         const agentId = operation.agentId;
         // For createNotebook, route to ANY connected UI (not path-specific)
-        // This allows the UI to open the new notebook in a new tab
+        // This allows the UI to open the new notebook in a new tab.
+        // EXCEPT text notebook formats (.py/.qmd): the UI's create handler only
+        // builds Jupyter JSON, so those are always created headless through the
+        // format adapters.
         const isCreateNotebook = opType === 'createNotebook';
-        const anyUI = isCreateNotebook ? this.getAnyUIConnection() : null;
+        const isTextFormatCreate = isCreateNotebook && (0, registry_1.isTextNotebookPath)(operation.notebookPath || '');
+        const anyUI = isCreateNotebook && !isTextFormatCreate ? this.getAnyUIConnection() : null;
         const hasUI = isCreateNotebook ? (anyUI !== null) : (this.getResponsiveUIConnection(normalizedPath) !== null);
         const backend = hasUI ? 'ui' : 'headless';
         // Clean up expired locks
@@ -321,7 +349,8 @@ class OperationRouter {
             const clientName = operation.clientName;
             const clientVersion = operation.clientVersion;
             const lastSessionTimestamp = operation.lastSessionTimestamp;
-            const result = this.startAgentSession(notebookPath, reqAgentId, { clientName, clientVersion });
+            const exclusive = operation.exclusive === true;
+            const result = this.startAgentSession(notebookPath, reqAgentId, { clientName, clientVersion, exclusive });
             // Also forward to UI for UI state update (badge display)
             if (result.success && hasUI) {
                 console.log(`  -> Lock acquired, forwarding to UI for badge update`);
@@ -380,19 +409,197 @@ class OperationRouter {
         if (lock && agentId && lock.agentId === agentId) {
             lock.expiresAt = Date.now() + AGENT_LOCK_TIMEOUT_MS;
         }
+        // Collaborative sessions: stamp destructive writes with the content hash
+        // the agent last saw, to be compared against live content at the applier
+        // (the UI when connected — the only place with a freshness-window-free
+        // view, since user edits reach the server only on autosave).
+        if (isWrite && lock && !lock.exclusive && agentId && lock.agentId === agentId) {
+            const occError = this.prepareCollaborativeWrite(lock, operation, opType);
+            if (occError) {
+                console.log(`  -> BLOCKED (OCC): ${occError}`);
+                return { success: false, error: occError, conflict: true, backend };
+            }
+        }
+        let result;
         if (hasUI) {
             // For createNotebook, use any available UI connection
             const uiPath = isCreateNotebook && anyUI ? anyUI.path : normalizedPath;
             console.log(`  -> Routing to UI (via ${uiPath})`);
-            const result = await this.forwardToUI(uiPath, operation);
-            return { ...result, backend: 'ui' };
+            result = { ...(await this.forwardToUI(uiPath, operation)), backend: 'ui' };
         }
         else {
             console.log(`  -> Routing to HEADLESS`);
-            const result = await this.applyHeadless(operation);
-            return { ...result, backend: 'headless' };
+            result = { ...(await this.applyHeadless(operation)), backend: 'headless' };
+        }
+        // Keep the session's view of cell content fresh from reads and the
+        // agent's own successful writes.
+        if (result.success) {
+            this.recordSessionHashes(normalizedPath, opType, operation, result);
+        }
+        else if (result.conflict && typeof result.currentContent === 'string' && typeof operation.cellId === 'string') {
+            // Self-healing conflicts: the error hands the agent the current content,
+            // so re-baseline the session to the same content. The agent's corrected
+            // retry then validates against what it was just told — without this, the
+            // stale stored hash rejects every retry until an explicit re-read.
+            const lock2 = this.agentLocks.get(normalizedPath);
+            const hashes = (lock2 && lock2.expiresAt > Date.now())
+                ? lock2.cellHashes
+                : this.getPreSessionStore(normalizedPath);
+            hashes.set(operation.cellId, (0, cell_hash_1.hashCellContent)(result.currentContent));
+        }
+        return result;
+    }
+    /**
+     * OCC preparation for a destructive write in a collaborative session.
+     * Returns an error string to reject the operation, or null to proceed
+     * (with `expectedHash`/`expectedHashes` stamped onto the operation).
+     *
+     * Policy:
+     * - updateContent / updateMetadata / deleteCell / deleteCells: the agent
+     *   must have read the cell this session (hash known), and the applier
+     *   verifies the content still matches before applying.
+     * - executeCell: verified only when the hash is known (running slightly
+     *   stale content is recoverable; destroying user edits is not).
+     * - clearNotebook: requires an exclusive session.
+     * - Index-addressed destructive writes are rejected: user edits shift
+     *   indices, so collaborative writes must address cells by id.
+     */
+    prepareCollaborativeWrite(lock, operation, opType) {
+        const requireHash = (cellId) => {
+            if (typeof cellId !== 'string' || !cellId) {
+                return `${opType} in a collaborative session must address the cell by cell_id (indices shift when the user edits). Re-read the notebook and use ids.`;
+            }
+            const hash = lock.cellHashes.get(cellId);
+            if (!hash) {
+                return `You haven't read cell ${cellId} in this session — read it first (read_cell), then retry. In collaborative sessions the user may edit while you work.`;
+            }
+            return null;
+        };
+        switch (opType) {
+            case 'updateContent':
+            case 'updateMetadata':
+            case 'deleteCell': {
+                const cellId = operation.cellId ?? null;
+                const err = requireHash(cellId);
+                if (err)
+                    return err;
+                operation.expectedHash = lock.cellHashes.get(cellId);
+                return null;
+            }
+            case 'deleteCells': {
+                const cellIds = Array.isArray(operation.cellIds) ? operation.cellIds : [];
+                const hashes = {};
+                for (const cellId of cellIds) {
+                    const err = requireHash(cellId);
+                    if (err)
+                        return err;
+                    hashes[cellId] = lock.cellHashes.get(cellId);
+                }
+                operation.expectedHashes = hashes;
+                return null;
+            }
+            case 'executeCell': {
+                const cellId = operation.cellId;
+                if (typeof cellId === 'string' && lock.cellHashes.has(cellId)) {
+                    operation.expectedHash = lock.cellHashes.get(cellId);
+                }
+                return null;
+            }
+            case 'clearNotebook':
+                return 'clearNotebook requires an exclusive session (start_agent_session with exclusive=true) — it would destroy any concurrent user edits.';
+            case 'undo':
+            case 'redo':
+                // Content shifts unpredictably — force re-reads afterwards.
+                lock.cellHashes.clear();
+                return null;
+            default:
+                return null; // insert/move/duplicate/outputs/kernel ops: not destructive to user content
+        }
+    }
+    /**
+     * Record the session's view of cell content from operation results.
+     * Keyed to the notebook's active lock: the lock guarantees a single writing
+     * agent per notebook, so reads from any source refreshing it is sound.
+     */
+    recordSessionHashes(normalizedPath, opType, operation, result) {
+        const lock = this.agentLocks.get(normalizedPath);
+        const hashes = (lock && lock.expiresAt > Date.now())
+            ? lock.cellHashes
+            : this.getPreSessionStore(normalizedPath); // pre-session reads arm OCC too
+        const record = (cellId, content) => {
+            if (typeof cellId === 'string' && typeof content === 'string') {
+                hashes.set(cellId, (0, cell_hash_1.hashCellContent)(content));
+            }
+        };
+        switch (opType) {
+            case 'readCell': {
+                const cell = result.cell;
+                record(cell?.id, cell?.content);
+                break;
+            }
+            case 'updateContent':
+                record(operation.cellId, operation.content);
+                break;
+            case 'insertCell': {
+                const cell = operation.cell;
+                record(result.cellId, cell?.content ?? '');
+                break;
+            }
+            case 'insertCells': {
+                const cells = operation.cells;
+                const insertedIds = result.cellIds;
+                if (cells && insertedIds && cells.length === insertedIds.length) {
+                    insertedIds.forEach((id, i) => record(id, cells[i]?.content ?? ''));
+                }
+                break;
+            }
+            case 'deleteCell':
+                if (typeof operation.cellId === 'string')
+                    hashes.delete(operation.cellId);
+                break;
+            case 'deleteCells':
+                if (Array.isArray(operation.cellIds)) {
+                    for (const id of operation.cellIds) {
+                        if (typeof id === 'string')
+                            hashes.delete(id);
+                    }
+                }
+                break;
+            case 'clearNotebook':
+                hashes.clear();
+                break;
         }
     }
+    /**
+     * Record hashes for a full-notebook read (used by router.readNotebook,
+     * which serves the MCP read_notebook tool outside applyOperation).
+     */
+    recordNotebookReadHashes(notebookPath, cells) {
+        const normalizedPath = normalizeNotebookPath(notebookPath);
+        const lock = this.agentLocks.get(normalizedPath);
+        const target = (lock && lock.expiresAt > Date.now())
+            ? lock.cellHashes
+            : this.getPreSessionStore(normalizedPath);
+        for (const cell of cells) {
+            if (typeof cell?.id === 'string' && typeof cell?.content === 'string') {
+                target.set(cell.id, (0, cell_hash_1.hashCellContent)(cell.content));
+            }
+        }
+    }
+    getPreSessionStore(normalizedPath) {
+        let store = this.preSessionReadHashes.get(normalizedPath);
+        if (!store) {
+            store = new Map();
+            this.preSessionReadHashes.set(normalizedPath, store);
+            // Bound total memory: keep at most a handful of notebooks' worth.
+            if (this.preSessionReadHashes.size > 16) {
+                const oldest = this.preSessionReadHashes.keys().next().value;
+                if (oldest && oldest !== normalizedPath)
+                    this.preSessionReadHashes.delete(oldest);
+            }
+        }
+        return store;
+    }
     async forwardToUI(notebookPath, operation) {
         const conn = this.getResponsiveUIConnection(notebookPath);
         if (!conn) {
@@ -492,6 +699,9 @@ class OperationRouter {
         if (this.getResponsiveUIConnection(normalizedPath)) {
             const result = await this.readFromUI(normalizedPath);
             if (result.success) {
+                const data = result.data;
+                if (data?.cells)
+                    this.recordNotebookReadHashes(normalizedPath, data.cells);
                 const truncated = this.applyOutputTruncation(result, includeOutputs, maxLines, maxChars, maxLinesError, maxCharsError);
                 if (!truncated.backend) {
                     truncated.backend = 'ui';
@@ -505,6 +715,11 @@ class OperationRouter {
         }
         else {
             const result = await this.readFromFile(notebookPath, includeOutputs, maxLines, maxChars, maxLinesError, maxCharsError);
+            if (result.success) {
+                const data = result.data;
+                if (data?.cells)
+                    this.recordNotebookReadHashes(normalizedPath, data.cells);
+            }
             if (!result.backend) {
                 result.backend = 'headless';
             }