nebula-notebook 0.1.1 → 0.2.1

package/node-server/dist/fs/fs-service.js

@@ -40,11 +40,15 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fsService = exports.FilesystemService = void 0;
 const fs = __importStar(require("fs"));
+const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const crypto = __importStar(require("crypto"));
 const util_1 = require("util");
+const types_1 = require("./types");
 const default_kernel_1 = require("../kernel/default-kernel");
+const registry_1 = require("./notebook-formats/registry");
+const percent_1 = require("./notebook-formats/percent");
 const display_data_1 = require("../output/display-data");
 const NEBULA_DIR = path.join(os.homedir(), '.nebula');
 const USER_CONFIG_PATH = path.join(NEBULA_DIR, 'config.json');
@@ -345,6 +349,52 @@ class FilesystemService {
     writeJsonAtomicSync(targetPath, payload) {
         this.atomicWriteFileSync(targetPath, JSON.stringify(payload, null, 2));
     }
+    /**
+     * Async variant of atomicWriteFileSync (write temp, fsync, rename, fsync dir).
+     * Used on hot notebook-save paths so large writes never block the event loop.
+     *
+     * `durable: false` skips both fsyncs while keeping the tmp+rename atomicity.
+     * Use it for auxiliary files (history/session/journal/lastsave): on network
+     * filesystems (GPFS) each fsync can take seconds, and a save doing ~10 of
+     * them was observed at 20-27s. A crash can lose the last few seconds of an
+     * auxiliary file, but never corrupt it — the rename is still atomic. The
+     * notebook file itself stays fully durable.
+     */
+    async atomicWriteFile(targetPath, data, opts = {}) {
+        const durable = opts.durable !== false;
+        const dir = path.dirname(targetPath);
+        await fs_1.promises.mkdir(dir, { recursive: true });
+        const tmpName = `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+        const tmpPath = path.join(dir, tmpName);
+        const handle = await fs_1.promises.open(tmpPath, 'w', 0o600);
+        try {
+            await handle.writeFile(data, 'utf-8');
+            if (durable)
+                await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs_1.promises.rename(tmpPath, targetPath);
+        if (!durable)
+            return;
+        // Best-effort directory fsync
+        try {
+            const dirHandle = await fs_1.promises.open(dir, 'r');
+            try {
+                await dirHandle.sync();
+            }
+            finally {
+                await dirHandle.close();
+            }
+        }
+        catch {
+            // Ignore fsync errors on directory handles
+        }
+    }
+    async writeJsonAtomic(targetPath, payload, opts = {}) {
+        await this.atomicWriteFile(targetPath, JSON.stringify(payload, null, 2), opts);
+    }
     /**
      * Format file size for display
      */
@@ -367,10 +417,10 @@ class FilesystemService {
      */
     getFileType(extension) {
         const ext = extension.toLowerCase();
-        if (ext === '.ipynb') {
+        if (ext === '.ipynb' || ext === '.qmd') {
             return 'notebook';
         }
-        else if (['.py', '.js', '.ts', '.tsx', '.jsx', '.json', '.yaml', '.yml', '.toml', '.md', '.txt'].includes(ext)) {
+        else if (['.py', '.r', '.jl', '.js', '.ts', '.tsx', '.jsx', '.json', '.yaml', '.yml', '.toml', '.md', '.txt'].includes(ext)) {
             return 'code';
         }
         else if (['.csv', '.tsv', '.xlsx', '.xls'].includes(ext)) {
@@ -400,6 +450,21 @@ class FilesystemService {
             extension: isDir ? '' : path.extname(name),
         };
     }
+    /** Async, non-blocking variant of getFileInfo (one `fsp.stat`). Used by
+     *  listDirectory so a folder's entries stat in parallel off the event loop. */
+    async getFileInfoAsync(filePath) {
+        const stat = await fs_1.promises.stat(filePath);
+        const name = path.basename(filePath);
+        const isDir = stat.isDirectory();
+        return {
+            name,
+            path: filePath,
+            isDirectory: isDir,
+            size: isDir ? 0 : stat.size,
+            modified: stat.mtimeMs / 1000,
+            extension: isDir ? '' : path.extname(name),
+        };
+    }
     /**
      * Convert FileInfo to FileInfoResponse for API
      */
@@ -436,12 +501,16 @@ class FilesystemService {
     /**
      * Get file modification time
      */
-    getFileMtime(filePath) {
+    async getFileMtime(filePath) {
         const normalizedPath = this.normalizePath(filePath);
-        if (!fs.existsSync(normalizedPath)) {
+        let stat;
+        try {
+            stat = await fs_1.promises.stat(normalizedPath);
+        }
+        catch {
+            // Matches the sync existsSync() behavior: any stat failure reads as missing
             throw new Error(`File not found: ${normalizedPath}`);
         }
-        const stat = fs.statSync(normalizedPath);
         return {
             path: normalizedPath,
             mtime: stat.mtimeMs / 1000,
@@ -450,32 +519,35 @@ class FilesystemService {
     /**
      * List contents of a directory
      */
-    listDirectory(dirPath) {
+    async listDirectory(dirPath) {
         const normalizedPath = this.normalizePath(dirPath);
-        if (!fs.existsSync(normalizedPath)) {
+        let stat;
+        try {
+            stat = await fs_1.promises.stat(normalizedPath);
+        }
+        catch {
             throw new Error(`Path not found: ${normalizedPath}`);
         }
-        const stat = fs.statSync(normalizedPath);
         if (!stat.isDirectory()) {
             throw new Error(`Not a directory: ${normalizedPath}`);
         }
-        const items = [];
-        const entries = fs.readdirSync(normalizedPath);
-        for (const name of entries) {
-            // Skip hidden files
-            if (name.startsWith('.')) {
-                continue;
-            }
-            const fullPath = path.join(normalizedPath, name);
+        const entries = await fs_1.promises.readdir(normalizedPath);
+        // Stat every visible entry in PARALLEL rather than one blocking statSync at a
+        // time. On a network filesystem a serial loop stalls the single event
+        // loop for N × stat-latency, delaying every other in-flight request (kernel
+        // starts, terminal creation, saves) — the source of the "everything hangs
+        // while a folder lists" latency.
+        const settled = await Promise.all(entries
+            .filter((name) => !name.startsWith('.')) // skip hidden files
+            .map(async (name) => {
             try {
-                const info = this.getFileInfo(fullPath);
-                items.push(this.toFileInfoResponse(info));
+                return this.toFileInfoResponse(await this.getFileInfoAsync(path.join(normalizedPath, name)));
             }
             catch {
-                // Skip files we can't access
-                continue;
+                return null; // skip entries we can't access
             }
-        }
+        }));
+        const items = settled.filter((x) => x !== null);
         // Sort: directories first, then by name
         items.sort((a, b) => {
             if (a.isDirectory !== b.isDirectory) {
@@ -493,18 +565,22 @@ class FilesystemService {
     /**
      * Read a file's contents
      */
-    readFile(filePath) {
+    async readFile(filePath) {
         const normalizedPath = this.normalizePath(filePath);
-        if (!fs.existsSync(normalizedPath)) {
+        let stat;
+        try {
+            stat = await fs_1.promises.stat(normalizedPath);
+        }
+        catch {
+            // Matches the sync existsSync() behavior: any stat failure reads as missing
             throw new Error(`File not found: ${normalizedPath}`);
         }
-        const stat = fs.statSync(normalizedPath);
         if (stat.isDirectory()) {
             throw new Error(`Path is a directory: ${normalizedPath}`);
         }
         const extension = path.extname(normalizedPath).toLowerCase();
         if (extension === '.ipynb') {
-            const content = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
+            const content = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
             return {
                 path: normalizedPath,
                 type: 'notebook',
@@ -513,7 +589,7 @@ class FilesystemService {
         }
         // Try to read as text
         try {
-            const content = fs.readFileSync(normalizedPath, 'utf-8');
+            const content = await fs_1.promises.readFile(normalizedPath, 'utf-8');
             return {
                 path: normalizedPath,
                 type: 'text',
@@ -582,6 +658,16 @@ class FilesystemService {
                 };
                 this.writeJsonAtomicSync(normalizedPath, notebook);
             }
+            else if (extension === '.qmd') {
+                // Text-format notebook template (NOT .py: creating a .py must stay a
+                // plain empty script — percent parsing only applies when one is
+                // opened as a notebook)
+                const adapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+                this.atomicWriteFileSync(normalizedPath, adapter.serialize([], {
+                    kernelspec: { display_name: 'Python 3', language: 'python', name: 'python3' },
+                    __qmd_language: 'python',
+                }));
+            }
             else {
                 // Create empty file
                 fs.writeFileSync(normalizedPath, '', 'utf-8');
@@ -597,6 +683,31 @@ class FilesystemService {
         const { nebulaDir, nameWithoutExt } = this.getNebulaPaths(notebookPath);
         return path.join(nebulaDir, `${nameWithoutExt}.history.json`);
     }
+    /**
+     * Last-Nebula-save record for text-format notebooks: the canonical cell
+     * state (id/type/content) as of the last save THROUGH Nebula. At history
+     * load, divergence between this record and the file means the notebook was
+     * edited externally (vim, git checkout, ...) — the difference is
+     * reconciled into history as a synthesized external-edit operation so
+     * undo/redo stays infinite across external edits.
+     */
+    getLastSavePath(notebookPath) {
+        const { nebulaDir, nameWithoutExt } = this.getNebulaPaths(notebookPath);
+        return path.join(nebulaDir, `${nameWithoutExt}.lastsave.json`);
+    }
+    async writeTextNotebookLastSave(notebookPath, serializedText, adapter) {
+        try {
+            // Record the POST-round-trip identity (parse of what was written), so
+            // positional ids (qmd markdown cells) never read as false divergence.
+            const canonical = adapter.parse(serializedText).cells;
+            await this.writeJsonAtomic(this.getLastSavePath(notebookPath), {
+                cells: canonical.map((c) => ({ id: c.id, type: c.type, content: c.content })),
+            }, { durable: false });
+        }
+        catch (e) {
+            console.warn('[FilesystemService] Failed to write lastsave record:', e);
+        }
+    }
     /**
      * Get the session state file path for a notebook
      */
@@ -632,7 +743,13 @@ class FilesystemService {
         const normalizedPath = this.normalizePath(notebookPath);
         const parentDir = path.dirname(normalizedPath);
         const notebookName = path.basename(normalizedPath);
-        const nameWithoutExt = path.basename(notebookName, path.extname(notebookName));
+        // .ipynb sidecar names are extension-stripped (unchanged, pre-existing
+        // files keep working). Text-format notebooks keep their full basename so
+        // foo.py and foo.ipynb in one directory never share sidecars.
+        const ext = path.extname(notebookName).toLowerCase();
+        const nameWithoutExt = ext === '.ipynb'
+            ? path.basename(notebookName, path.extname(notebookName))
+            : notebookName;
         const nebulaDir = path.join(parentDir, '.nebula');
         return { nebulaDir, nameWithoutExt };
     }
@@ -643,6 +760,10 @@ class FilesystemService {
         const historyPath = this.getHistoryPath(notebookPath);
         const sessionPath = this.getSessionPath(notebookPath);
         const journalPath = this.getJournalPath(notebookPath);
+        const lastSavePath = this.getLastSavePath(notebookPath);
+        if (fs.existsSync(lastSavePath)) {
+            fs.unlinkSync(lastSavePath);
+        }
         if (fs.existsSync(historyPath)) {
             fs.unlinkSync(historyPath);
         }
@@ -662,9 +783,8 @@ class FilesystemService {
             throw new Error(`Path not found: ${normalizedPath}`);
         }
         // For notebooks, also delete history and session files
-        const ext = path.extname(normalizedPath).toLowerCase();
         const stat = fs.statSync(normalizedPath);
-        if (ext === '.ipynb' && !stat.isDirectory()) {
+        if ((0, registry_1.isNotebookPath)(normalizedPath) && !stat.isDirectory()) {
             this.deleteNotebookMetadata(normalizedPath);
         }
         if (stat.isDirectory()) {
@@ -699,6 +819,10 @@ class FilesystemService {
             // Journal files are ephemeral; remove any stale commit record on rename
             fs.unlinkSync(oldJournal);
         }
+        const oldLastSave = this.getLastSavePath(oldPath);
+        if (fs.existsSync(oldLastSave)) {
+            fs.renameSync(oldLastSave, this.getLastSavePath(newPath));
+        }
     }
     /**
      * Rename/move a file or directory
@@ -713,8 +837,7 @@ class FilesystemService {
             throw new Error(`Destination already exists: ${normalizedNew}`);
         }
         // For notebooks, also rename history and session files
-        const ext = path.extname(normalizedOld).toLowerCase();
-        if (ext === '.ipynb') {
+        if ((0, registry_1.isNotebookPath)(normalizedOld)) {
             this.renameNotebookMetadata(normalizedOld, normalizedNew);
         }
         fs.renameSync(normalizedOld, normalizedNew);
@@ -728,6 +851,14 @@ class FilesystemService {
         const destHistory = this.getHistoryPath(destPath);
         const srcSession = this.getSessionPath(srcPath);
         const destSession = this.getSessionPath(destPath);
+        const srcLastSave = this.getLastSavePath(srcPath);
+        if (fs.existsSync(srcLastSave)) {
+            const destNebulaDirForLastSave = path.dirname(destHistory);
+            if (!fs.existsSync(destNebulaDirForLastSave)) {
+                fs.mkdirSync(destNebulaDirForLastSave, { recursive: true });
+            }
+            fs.copyFileSync(srcLastSave, this.getLastSavePath(destPath));
+        }
         // Create destination .nebula directory if needed
         const destNebulaDir = path.dirname(destHistory);
         if (!fs.existsSync(destNebulaDir)) {
@@ -758,7 +889,7 @@ class FilesystemService {
                 }
                 fs.copyFileSync(srcPath, destPath);
                 // For notebooks, also duplicate history and session files
-                if (entry.name.toLowerCase().endsWith('.ipynb')) {
+                if ((0, registry_1.isNotebookPath)(entry.name)) {
                     this.duplicateNotebookMetadata(srcPath, destPath);
                 }
             }
@@ -794,7 +925,7 @@ class FilesystemService {
             // Copy the file
             fs.copyFileSync(normalizedPath, newPath);
             // For notebooks, also duplicate history and session files
-            if (ext.toLowerCase() === '.ipynb') {
+            if ((0, registry_1.isNotebookPath)(normalizedPath)) {
                 this.duplicateNotebookMetadata(normalizedPath, newPath);
             }
         }
@@ -959,14 +1090,58 @@ class FilesystemService {
         return result;
     }
     /**
-     * Read a notebook and convert to internal cell format
+     * Read a notebook and convert to internal cell format (async; hot path for
+     * notebook load — large .ipynb reads must not block the event loop)
+     */
+    async getNotebookCells(notebookPath) {
+        const normalizedPath = this.normalizePath(notebookPath);
+        let raw;
+        let stat;
+        try {
+            [raw, stat] = await Promise.all([
+                fs_1.promises.readFile(normalizedPath, 'utf-8'),
+                fs_1.promises.stat(normalizedPath),
+            ]);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                throw new Error(`Notebook not found: ${normalizedPath}`);
+            }
+            throw err;
+        }
+        return this.buildNotebookCellsResponse(normalizedPath, raw, stat.mtimeMs);
+    }
+    /**
+     * Sync variant of getNotebookCells. Kept for cold callers that need a
+     * synchronous read (headless cache warm-up, initial-history bootstrap).
      */
-    getNotebookCells(notebookPath) {
+    getNotebookCellsSync(notebookPath) {
         const normalizedPath = this.normalizePath(notebookPath);
         if (!fs.existsSync(normalizedPath)) {
             throw new Error(`Notebook not found: ${normalizedPath}`);
         }
-        const notebook = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
+        const raw = fs.readFileSync(normalizedPath, 'utf-8');
+        const stat = fs.statSync(normalizedPath);
+        return this.buildNotebookCellsResponse(normalizedPath, raw, stat.mtimeMs);
+    }
+    /**
+     * Convert raw notebook file content to the internal cell format (CPU only).
+     */
+    buildNotebookCellsResponse(normalizedPath, raw, mtimeMs) {
+        // Text notebook formats (.py percent / .qmd): adapter path. The .ipynb
+        // body below is untouched.
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        if (formatAdapter) {
+            const parsed = formatAdapter.parse(raw);
+            return {
+                cells: parsed.cells,
+                metadata: parsed.metadata,
+                kernelspec: parsed.kernelspecName || (0, registry_1.defaultKernelForPath)(normalizedPath),
+                kernelspecSource: parsed.kernelspecName ? 'metadata' : 'default',
+                mtime: mtimeMs / 1000,
+            };
+        }
+        const notebook = JSON.parse(raw);
         const metadataKernel = notebook.metadata?.kernelspec?.name;
         const kernelspec = metadataKernel || 'python3';
         const cells = notebook.cells.map((nbCell, i) => {
@@ -1001,20 +1176,19 @@ class FilesystemService {
             }
             return cell;
         });
-        const stat = fs.statSync(normalizedPath);
         return {
             cells,
             metadata: notebook.metadata || {},
             kernelspec,
             kernelspecSource: metadataKernel ? 'metadata' : 'default',
-            mtime: stat.mtimeMs / 1000,
+            mtime: mtimeMs / 1000,
         };
     }
     /**
      * Read a notebook and convert to internal cell format, resolving default kernel if needed
      */
     async getNotebookCellsWithKernel(notebookPath) {
-        const result = this.getNotebookCells(notebookPath);
+        const result = await this.getNotebookCells(notebookPath);
         if (result.kernelspecSource === 'metadata') {
             return result;
         }
@@ -1036,36 +1210,66 @@ class FilesystemService {
     /**
      * Save cells to a notebook file
      */
-    saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata) {
+    async saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata) {
         const normalizedPath = this.normalizePath(notebookPath);
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        if (formatAdapter) {
+            return await this.saveTextNotebookCells(formatAdapter, normalizedPath, cells, kernelName, notebookMetadata);
+        }
         // Load existing notebook metadata if file exists.
         // Prefer a fast scan for the top-level metadata object so we avoid
         // parsing the full notebook on every save. Fall back to full JSON
         // parsing only for smaller notebooks when the fast path cannot find it.
         let existingMetadata = {};
-        if (fs.existsSync(normalizedPath)) {
+        try {
+            const stat = await fs_1.promises.stat(normalizedPath);
+            const handle = await fs_1.promises.open(normalizedPath, 'r');
+            let head;
             try {
-                const stat = fs.statSync(normalizedPath);
-                const fd = fs.openSync(normalizedPath, 'r');
                 const buf = Buffer.alloc(NOTEBOOK_METADATA_FAST_PATH_BYTES);
-                const bytesRead = fs.readSync(fd, buf, 0, NOTEBOOK_METADATA_FAST_PATH_BYTES, 0);
-                fs.closeSync(fd);
-                const head = buf.toString('utf-8', 0, bytesRead);
-                const extractedMetadata = extractTopLevelObjectField(head, 'metadata');
-                if (extractedMetadata) {
-                    existingMetadata = extractedMetadata;
-                }
-                else if (stat.size <= NOTEBOOK_METADATA_FALLBACK_PARSE_BYTES) {
-                    const notebook = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
-                    existingMetadata = notebook.metadata || {};
-                }
+                const { bytesRead } = await handle.read(buf, 0, NOTEBOOK_METADATA_FAST_PATH_BYTES, 0);
+                head = buf.toString('utf-8', 0, bytesRead);
             }
-            catch {
-                // Start fresh — metadata extraction failed
+            finally {
+                await handle.close();
+            }
+            const extractedMetadata = extractTopLevelObjectField(head, 'metadata');
+            if (extractedMetadata) {
+                existingMetadata = extractedMetadata;
             }
+            else if (stat.size <= NOTEBOOK_METADATA_FALLBACK_PARSE_BYTES) {
+                const notebook = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
+                existingMetadata = notebook.metadata || {};
+            }
+        }
+        catch {
+            // Start fresh — file missing or metadata extraction failed
         }
         kernelName = kernelName || 'python3';
         const displayName = kernelName === 'python3' ? 'Python 3' : kernelName.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        // Resolve outputs-unchanged sentinels from the file on disk: the client
+        // elides unchanged outputs (often MBs of base64 images) from autosaves so
+        // slow uplinks aren't saturated. If anything can't be resolved, ask the
+        // client to retry with a full payload rather than guessing.
+        const sentinelCells = cells.filter((c) => c.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL);
+        const priorOutputs = new Map();
+        if (sentinelCells.length > 0) {
+            try {
+                const existing = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
+                for (const jc of existing.cells || []) {
+                    const nid = jc.metadata?.nebula_id;
+                    if (nid)
+                        priorOutputs.set(String(nid), { outputs: jc.outputs || [], execution_count: jc.execution_count ?? null });
+                }
+            }
+            catch {
+                return { success: false, mtime: 0, needsFull: true };
+            }
+            for (const c of sentinelCells) {
+                if (!priorOutputs.has(c.id))
+                    return { success: false, mtime: 0, needsFull: true };
+            }
+        }
         const nbCells = cells.map((cell) => {
             const preservedMetadata = cell._metadata || {};
             const cellMetadata = {
@@ -1084,8 +1288,15 @@ class FilesystemService {
                 metadata: cellMetadata,
             };
             if (cell.type === 'code') {
-                nbCell.outputs = this.convertOutputsToJupyter(cell.outputs);
-                nbCell.execution_count = cell.executionCount;
+                if (cell.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL) {
+                    const prior = priorOutputs.get(cell.id);
+                    nbCell.outputs = prior.outputs;
+                    nbCell.execution_count = cell.executionCount ?? prior.execution_count;
+                }
+                else {
+                    nbCell.outputs = this.convertOutputsToJupyter(cell.outputs);
+                    nbCell.execution_count = cell.executionCount;
+                }
             }
             return nbCell;
         });
@@ -1122,11 +1333,9 @@ class FilesystemService {
         };
         // Create parent directory if needed
         const parentDir = path.dirname(normalizedPath);
-        if (!fs.existsSync(parentDir)) {
-            fs.mkdirSync(parentDir, { recursive: true });
-        }
-        this.writeJsonAtomicSync(normalizedPath, notebook);
-        const stat = fs.statSync(normalizedPath);
+        await fs_1.promises.mkdir(parentDir, { recursive: true });
+        await this.writeJsonAtomic(normalizedPath, notebook);
+        const stat = await fs_1.promises.stat(normalizedPath);
         return {
             success: true,
             mtime: stat.mtimeMs / 1000,
@@ -1157,25 +1366,25 @@ class FilesystemService {
             };
             // Ensure .nebula directory exists for journal/history/session
             const { nebulaDir } = this.getNebulaPaths(notebookPath);
-            if (!fs.existsSync(nebulaDir)) {
-                fs.mkdirSync(nebulaDir, { recursive: true });
-            }
-            this.writeJsonAtomicSync(journalPath, journal);
+            await fs_1.promises.mkdir(nebulaDir, { recursive: true });
+            // Auxiliary files: atomic but non-durable (no fsync) — see atomicWriteFile.
+            // Only the notebook itself (inside saveNotebookCells) pays for fsync.
+            await this.writeJsonAtomic(journalPath, journal, { durable: false });
             if (historyPath) {
-                this.writeJsonAtomicSync(historyPath, history || []);
+                await this.writeJsonAtomic(historyPath, history || [], { durable: false });
             }
             if (sessionPath) {
-                this.writeJsonAtomicSync(sessionPath, session || {});
+                await this.writeJsonAtomic(sessionPath, session || {}, { durable: false });
             }
-            const result = this.saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata);
+            const result = await this.saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata);
             const committedJournal = {
                 ...journal,
                 status: 'commit',
                 committedAt: Date.now(),
             };
-            this.writeJsonAtomicSync(journalPath, committedJournal);
+            await this.writeJsonAtomic(journalPath, committedJournal, { durable: false });
             try {
-                fs.unlinkSync(journalPath);
+                await fs_1.promises.unlink(journalPath);
             }
             catch {
                 // Ignore cleanup errors; journal can be inspected if needed
@@ -1183,6 +1392,38 @@ class FilesystemService {
             return result;
         });
     }
+    /**
+     * Save cells to a text-format notebook (.py percent / .qmd).
+     * Outputs and execution counts are never serialized — by format design.
+     */
+    async saveTextNotebookCells(adapter, normalizedPath, cells, kernelName, notebookMetadata) {
+        // Text formats never serialize outputs; neutralize any outputs-unchanged
+        // sentinels so nothing downstream sees the marker string.
+        cells = cells.map((c) => c.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL ? { ...c, outputs: [] } : c);
+        let existingMetadata = {};
+        try {
+            existingMetadata = adapter.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8')).metadata;
+        }
+        catch {
+            // Start fresh — file missing or metadata extraction failed
+        }
+        const finalMetadata = { ...existingMetadata };
+        if (notebookMetadata) {
+            for (const [key, value] of Object.entries(notebookMetadata)) {
+                if (typeof value === 'object' && value !== null && typeof finalMetadata[key] === 'object' && finalMetadata[key] !== null) {
+                    finalMetadata[key] = { ...finalMetadata[key], ...value };
+                }
+                else {
+                    finalMetadata[key] = value;
+                }
+            }
+        }
+        const text = adapter.serialize(cells, finalMetadata, kernelName);
+        await this.atomicWriteFile(normalizedPath, text);
+        await this.writeTextNotebookLastSave(normalizedPath, text, adapter);
+        const stat = await fs_1.promises.stat(normalizedPath);
+        return { success: true, mtime: stat.mtimeMs / 1000 };
+    }
     /**
      * Get notebook-level metadata
      */
@@ -1191,6 +1432,15 @@ class FilesystemService {
         if (!fs.existsSync(normalizedPath)) {
             return {};
         }
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        if (formatAdapter) {
+            try {
+                return formatAdapter.parse(fs.readFileSync(normalizedPath, 'utf-8')).metadata;
+            }
+            catch {
+                return {};
+            }
+        }
         try {
             const notebook = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
             return notebook.metadata || {};
@@ -1199,17 +1449,91 @@ class FilesystemService {
             return {};
         }
     }
+    /**
+     * Async variant of getNotebookMetadata. Nebula-written notebooks put
+     * `metadata` first, so the head-bytes scan avoids reading and parsing the
+     * whole file; externally written notebooks fall back to a full async read.
+     */
+    async getNotebookMetadataAsync(notebookPath) {
+        const normalizedPath = this.normalizePath(notebookPath);
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        try {
+            if (formatAdapter) {
+                return formatAdapter.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8')).metadata;
+            }
+            const handle = await fs_1.promises.open(normalizedPath, 'r');
+            let head;
+            try {
+                const buf = Buffer.alloc(NOTEBOOK_METADATA_FAST_PATH_BYTES);
+                const { bytesRead } = await handle.read(buf, 0, NOTEBOOK_METADATA_FAST_PATH_BYTES, 0);
+                head = buf.toString('utf-8', 0, bytesRead);
+            }
+            finally {
+                await handle.close();
+            }
+            const extracted = extractTopLevelObjectField(head, 'metadata');
+            if (extracted) {
+                return extracted;
+            }
+            const notebook = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
+            return notebook.metadata || {};
+        }
+        catch {
+            return {};
+        }
+    }
     /**
      * Update notebook-level metadata without modifying cells
      */
     async updateNotebookMetadata(notebookPath, metadataUpdates) {
         return await this.withWriteLock(notebookPath, async () => {
             const normalizedPath = this.normalizePath(notebookPath);
-            if (!fs.existsSync(normalizedPath)) {
+            try {
+                await fs_1.promises.access(normalizedPath);
+            }
+            catch {
                 return { success: false, error: `Notebook not found: ${normalizedPath}` };
             }
+            const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+            if (formatAdapter) {
+                try {
+                    const rawText = await fs_1.promises.readFile(normalizedPath, 'utf-8');
+                    // A plain .py script (no markers, no header) must not be
+                    // Nebula-fied by metadata side effects — kernel attach and
+                    // settings writes are skipped until a content save makes the
+                    // file a notebook on purpose.
+                    if (formatAdapter.name === 'percent' && !(0, percent_1.isPercentNotebookText)(rawText)) {
+                        const stat = await fs_1.promises.stat(normalizedPath);
+                        return { success: true, changed: false, mtime: stat.mtimeMs / 1000 };
+                    }
+                    const parsed = formatAdapter.parse(rawText);
+                    const existingMetadata = parsed.metadata;
+                    const nextMetadata = { ...existingMetadata };
+                    for (const [key, value] of Object.entries(metadataUpdates)) {
+                        if (typeof value === 'object' && value !== null && typeof nextMetadata[key] === 'object' && nextMetadata[key] !== null) {
+                            nextMetadata[key] = {
+                                ...nextMetadata[key],
+                                ...value,
+                            };
+                        }
+                        else {
+                            nextMetadata[key] = value;
+                        }
+                    }
+                    if ((0, util_1.isDeepStrictEqual)(existingMetadata, nextMetadata)) {
+                        const stat = await fs_1.promises.stat(normalizedPath);
+                        return { success: true, changed: false, mtime: stat.mtimeMs / 1000 };
+                    }
+                    await this.atomicWriteFile(normalizedPath, formatAdapter.serialize(parsed.cells, nextMetadata));
+                    const stat = await fs_1.promises.stat(normalizedPath);
+                    return { success: true, changed: true, mtime: stat.mtimeMs / 1000 };
+                }
+                catch (e) {
+                    return { success: false, error: `Failed to update notebook: ${e}` };
+                }
+            }
             try {
-                const notebook = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
+                const notebook = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
                 const existingMetadata = notebook.metadata || {};
                 const nextMetadata = { ...existingMetadata };
                 for (const [key, value] of Object.entries(metadataUpdates)) {
@@ -1224,7 +1548,7 @@ class FilesystemService {
                     }
                 }
                 if ((0, util_1.isDeepStrictEqual)(existingMetadata, nextMetadata)) {
-                    const stat = fs.statSync(normalizedPath);
+                    const stat = await fs_1.promises.stat(normalizedPath);
                     return {
                         success: true,
                         changed: false,
@@ -1232,8 +1556,8 @@ class FilesystemService {
                     };
                 }
                 notebook.metadata = nextMetadata;
-                this.writeJsonAtomicSync(normalizedPath, notebook);
-                const stat = fs.statSync(normalizedPath);
+                await this.writeJsonAtomic(normalizedPath, notebook);
+                const stat = await fs_1.promises.stat(normalizedPath);
                 return {
                     success: true,
                     changed: true,
@@ -1255,7 +1579,7 @@ class FilesystemService {
         return snapshot;
     }
     buildInitialHistory(notebookPath) {
-        const { cells } = this.getNotebookCells(notebookPath);
+        const { cells } = this.getNotebookCellsSync(notebookPath);
         return [{
                 type: 'snapshot',
                 cells: cells.map(cell => this.stripOutputsForHistorySnapshot(cell)),
@@ -1271,6 +1595,34 @@ class FilesystemService {
             if (!fs.existsSync(normalizedPath)) {
                 return { success: false, error: `Notebook not found: ${normalizedPath}` };
             }
+            const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+            if (formatAdapter) {
+                try {
+                    const parsed = formatAdapter.parse(fs.readFileSync(normalizedPath, 'utf-8'));
+                    const nebula = (parsed.metadata.nebula || {});
+                    const nextMetadata = {
+                        ...parsed.metadata,
+                        nebula: { ...nebula, agent_permitted: permitted },
+                    };
+                    this.atomicWriteFileSync(normalizedPath, formatAdapter.serialize(parsed.cells, nextMetadata));
+                    if (permitted && !this.hasHistory(notebookPath)) {
+                        const historyPath = this.getHistoryPath(notebookPath);
+                        const nebulaDir = path.dirname(historyPath);
+                        if (!fs.existsSync(nebulaDir)) {
+                            fs.mkdirSync(nebulaDir, { recursive: true });
+                        }
+                        this.writeJsonAtomicSync(historyPath, this.buildInitialHistory(notebookPath));
+                    }
+                    return {
+                        success: true,
+                        status: this.getAgentPermissionStatus(notebookPath),
+                        mtime: fs.statSync(normalizedPath).mtimeMs / 1000,
+                    };
+                }
+                catch (e) {
+                    return { success: false, error: `Failed to set agent permission: ${e}` };
+                }
+            }
             try {
                 const notebook = JSON.parse(fs.readFileSync(normalizedPath, 'utf-8'));
                 const metadata = notebook.metadata || {};
@@ -1294,6 +1646,10 @@ class FilesystemService {
                 return {
                     success: true,
                     status: this.getAgentPermissionStatus(notebookPath),
+                    // The permission flag was just written INTO the notebook file; the
+                    // caller must adopt this mtime or its next autosave will mistake
+                    // our own write for an external change ("changed on server").
+                    mtime: fs.statSync(normalizedPath).mtimeMs / 1000,
                 };
             }
             catch (e) {
@@ -1306,31 +1662,57 @@ class FilesystemService {
      */
     getAgentPermissionStatus(notebookPath) {
         const metadata = this.getNotebookMetadata(notebookPath);
-        const nebula = (metadata.nebula || {});
         const hasHistory = this.hasHistory(notebookPath);
+        return this.deriveAgentPermission(metadata, hasHistory);
+    }
+    /**
+     * Async variant of getAgentPermissionStatus for hot request paths (it runs
+     * on every agent write operation). Reads metadata via the head-bytes fast
+     * path and checks history without parsing it, so the per-operation gate
+     * never blocks the event loop on a slow network filesystem.
+     */
+    async getAgentPermissionStatusAsync(notebookPath) {
+        const [metadata, hasHistory] = await Promise.all([
+            this.getNotebookMetadataAsync(notebookPath),
+            this.hasHistoryAsync(notebookPath),
+        ]);
+        return this.deriveAgentPermission(metadata, hasHistory);
+    }
+    deriveAgentPermission(metadata, hasHistory) {
+        const nebula = (metadata.nebula || {});
         const agentCreated = Boolean(nebula.agent_created);
         const agentPermitted = Boolean(nebula.agent_permitted);
-        const canModify = agentCreated || (agentPermitted && hasHistory);
+        // Tri-state: an explicit user revoke (agent_permitted === false) always wins,
+        // even for agent-created notebooks. Agent-created notebooks are permitted by
+        // default (unless revoked); other notebooks need an explicit user grant.
+        const revoked = nebula.agent_permitted === false;
+        const permitted = agentCreated ? !revoked : agentPermitted;
+        // Agent-created notebooks carry history from creation, so they skip the
+        // separate has-history gate that user-permitted notebooks require.
+        const canModify = permitted && (agentCreated || hasHistory);
         return {
             agent_created: agentCreated,
             agent_permitted: agentPermitted,
             has_history: hasHistory,
             can_agent_modify: canModify,
-            reason: agentCreated
-                ? 'Agent created this notebook'
+            reason: !permitted
+                ? (agentCreated ? 'Agent access revoked' : 'Not permitted for agent modifications')
                 : canModify
-                    ? 'User permitted and history enabled'
-                    : agentPermitted
-                        ? 'User permitted but history not enabled'
-                        : 'Not permitted for agent modifications',
+                    ? (agentCreated ? 'Agent created this notebook' : 'User permitted and history enabled')
+                    : 'User permitted but history not enabled',
         };
     }
     /**
      * Check if a notebook is permitted for agent modifications
      */
     isAgentPermitted(notebookPath) {
-        const status = this.getAgentPermissionStatus(notebookPath);
-        return status.agent_created || status.agent_permitted;
+        // Agent-created notebooks are permitted unless explicitly revoked; others
+        // require an explicit grant. A user revoke wins in both cases.
+        const metadata = this.getNotebookMetadata(notebookPath);
+        const nebula = (metadata.nebula || {});
+        const agentCreated = Boolean(nebula.agent_created);
+        const revoked = nebula.agent_permitted === false;
+        return agentCreated ? !revoked : Boolean(nebula.agent_permitted);
     }
     /**
      * Check if a notebook has history tracking enabled
@@ -1348,6 +1730,24 @@ class FilesystemService {
             return false;
         }
     }
+    /**
+     * Async variant of hasHistory that only parses small files: history journals
+     * grow to hundreds of KB, and this check runs on every agent operation — a
+     * file that large necessarily has entries, so its size alone answers.
+     */
+    async hasHistoryAsync(notebookPath) {
+        const historyPath = this.getHistoryPath(notebookPath);
+        try {
+            const stat = await fs_1.promises.stat(historyPath);
+            if (stat.size > 4096)
+                return true;
+            const history = JSON.parse(await fs_1.promises.readFile(historyPath, 'utf-8'));
+            return Array.isArray(history) && history.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Save operation history for a notebook
      */
@@ -1355,18 +1755,39 @@ class FilesystemService {
         const historyPath = this.getHistoryPath(notebookPath);
         // Create .nebula directory if needed
         const nebulaDir = path.dirname(historyPath);
-        if (!fs.existsSync(nebulaDir)) {
-            fs.mkdirSync(nebulaDir, { recursive: true });
-        }
+        await fs_1.promises.mkdir(nebulaDir, { recursive: true });
         await this.withWriteLock(notebookPath, async () => {
-            this.writeJsonAtomicSync(historyPath, history);
+            await this.writeJsonAtomic(historyPath, history);
         });
         return true;
     }
     /**
-     * Load operation history for a notebook
+     * Load operation history for a notebook (async; history files can be many MB)
+     */
+    async loadHistory(notebookPath) {
+        const historyPath = this.getHistoryPath(notebookPath);
+        if (this.hasPendingCommit(notebookPath)) {
+            console.warn(`[FilesystemService] Pending commit detected for ${notebookPath}; skipping history load.`);
+            return [];
+        }
+        let history;
+        try {
+            history = JSON.parse(await fs_1.promises.readFile(historyPath, 'utf-8'));
+        }
+        catch {
+            // Missing or unreadable/corrupt history file
+            return [];
+        }
+        // Text-format notebooks can be edited outside Nebula (that is their
+        // point); reconcile any divergence into history so undo/redo stays
+        // infinite across external edits. No-op for .ipynb.
+        return this.reconcileExternalTextEdits(notebookPath, history);
+    }
+    /**
+     * Sync variant of loadHistory. Kept for cold callers that need a
+     * synchronous read (headless undo/redo state bootstrap).
      */
-    loadHistory(notebookPath) {
+    loadHistorySync(notebookPath) {
         const historyPath = this.getHistoryPath(notebookPath);
         if (this.hasPendingCommit(notebookPath)) {
             console.warn(`[FilesystemService] Pending commit detected for ${notebookPath}; skipping history load.`);
@@ -1375,12 +1796,134 @@ class FilesystemService {
         if (!fs.existsSync(historyPath)) {
             return [];
         }
+        let history;
         try {
-            return JSON.parse(fs.readFileSync(historyPath, 'utf-8'));
+            history = JSON.parse(fs.readFileSync(historyPath, 'utf-8'));
         }
         catch {
             return [];
         }
+        return this.reconcileExternalTextEdits(notebookPath, history);
+    }
+    /**
+     * Compare the file's current cells against the last-Nebula-save record.
+     * On divergence, append ONE synthesized batch operation describing the
+     * external edit (updateContent / insertCell / deleteCell, source
+     * 'external') — both undo systems replay these, so a single undo step
+     * reverts the external edit and redo reapplies it. Falls back to a plain
+     * snapshot entry if synthesis fails (undo then bottoms out there instead
+     * of corrupting).
+     */
+    reconcileExternalTextEdits(notebookPath, history) {
+        const adapter = (0, registry_1.getFormatAdapter)(notebookPath);
+        if (!adapter || history.length === 0)
+            return history;
+        const normalizedPath = this.normalizePath(notebookPath);
+        const lastSavePath = this.getLastSavePath(notebookPath);
+        if (!fs.existsSync(normalizedPath) || !fs.existsSync(lastSavePath))
+            return history;
+        let currentCells;
+        try {
+            currentCells = adapter.parse(fs.readFileSync(normalizedPath, 'utf-8')).cells;
+        }
+        catch {
+            return history;
+        }
+        try {
+            const record = JSON.parse(fs.readFileSync(lastSavePath, 'utf-8'));
+            const before = record.cells ?? [];
+            const unchanged = before.length === currentCells.length &&
+                before.every((b, i) => currentCells[i].id === b.id &&
+                    currentCells[i].type === b.type &&
+                    currentCells[i].content === b.content);
+            if (unchanged)
+                return history;
+            const operations = this.synthesizeExternalEditOps(before, currentCells);
+            if (operations.length === 0)
+                return history;
+            const mtime = fs.statSync(normalizedPath).mtimeMs;
+            const entry = {
+                type: 'batch',
+                operations,
+                source: 'external',
+                operationId: `external-${crypto.randomBytes(6).toString('hex')}`,
+                timestamp: mtime,
+                external: true,
+            };
+            const next = [...history, entry];
+            this.writeJsonAtomicSync(this.getHistoryPath(notebookPath), next);
+            this.writeJsonAtomicSync(lastSavePath, {
+                cells: currentCells.map((c) => ({ id: c.id, type: c.type, content: c.content })),
+            });
+            console.log(`[FilesystemService] Reconciled external edit into history for ${notebookPath} (${operations.length} ops)`);
+            return next;
+        }
+        catch (e) {
+            console.warn('[FilesystemService] External-edit reconciliation failed; appending snapshot:', e);
+            try {
+                const snapshot = {
+                    type: 'snapshot',
+                    cells: currentCells.map((c) => this.stripOutputsForHistorySnapshot(c)),
+                    timestamp: fs.statSync(normalizedPath).mtimeMs,
+                    source: 'external',
+                };
+                const next = [...history, snapshot];
+                this.writeJsonAtomicSync(this.getHistoryPath(notebookPath), next);
+                this.writeJsonAtomicSync(lastSavePath, {
+                    cells: currentCells.map((c) => ({ id: c.id, type: c.type, content: c.content })),
+                });
+                return next;
+            }
+            catch {
+                return history;
+            }
+        }
+    }
+    synthesizeExternalEditOps(before, after) {
+        const toCell = (c) => ({
+            id: c.id,
+            type: c.type,
+            content: c.content,
+            outputs: [],
+            executionCount: null,
+            isExecuting: false,
+        });
+        const afterById = new Map(after.map((c, i) => [c.id, i]));
+        const beforeById = new Map(before.map((c, i) => [c.id, i]));
+        const ops = [];
+        // Deletions (and type changes) — descending index so replay indices hold
+        for (let i = before.length - 1; i >= 0; i--) {
+            const b = before[i];
+            const aIdx = afterById.get(b.id);
+            const a = aIdx !== undefined ? after[aIdx] : null;
+            if (!a || a.type !== b.type) {
+                ops.push({ type: 'deleteCell', index: i, cell: toCell(b), source: 'external' });
+            }
+        }
+        // Insertions (and the insert half of type changes) — ascending index
+        for (let i = 0; i < after.length; i++) {
+            const a = after[i];
+            const bIdx = beforeById.get(a.id);
+            const b = bIdx !== undefined ? before[bIdx] : null;
+            if (!b || b.type !== a.type) {
+                ops.push({
+                    type: 'insertCell',
+                    index: i,
+                    cell: { ...a, outputs: [], executionCount: null, isExecuting: false },
+                    source: 'external',
+                });
+            }
+            else if (b.content !== a.content) {
+                ops.push({
+                    type: 'updateContent',
+                    cellId: a.id,
+                    oldContent: b.content,
+                    newContent: a.content,
+                    source: 'external',
+                });
+            }
+        }
+        return ops;
     }
     /**
      * Save session state for a notebook
@@ -1389,11 +1932,9 @@ class FilesystemService {
         const sessionPath = this.getSessionPath(notebookPath);
         // Create .nebula directory if needed
         const nebulaDir = path.dirname(sessionPath);
-        if (!fs.existsSync(nebulaDir)) {
-            fs.mkdirSync(nebulaDir, { recursive: true });
-        }
+        await fs_1.promises.mkdir(nebulaDir, { recursive: true });
         await this.withWriteLock(notebookPath, async () => {
-            this.writeJsonAtomicSync(sessionPath, session);
+            await this.writeJsonAtomic(sessionPath, session);
         });
         return true;
     }