fix: resolve 12 session/file management bugs + add collab editing plan

- Fix URL hash not clearing when creating/switching files from shared doc
- Fix cloud auto-save overwriting all files to same Firebase doc
- Fix all flat disk API calls (readFile/writeFile/deleteFile) to use path-based variants for subdirectory support
- Fix boot-sequence content flicker when opening shared links
- Fix cloud timer not stopped on folder disconnect
- Add localStorage quota exceeded user toast
- Add persistent sidebar reconnect banner for expired folder permissions
- Add resetCloudForFileSwitch() API for per-file cloud doc isolation
- Add collaborative editing implementation plan (upgradePlan/)

Author: ijbo

changelogs/CHANGELOG-session-management.md

@@ -0,0 +1,50 @@
+# CHANGELOG — Session & File Management Fixes
+
+**Date:** 2026-03-16
+
+## Summary
+
+Comprehensive audit and fix of TextAgent's file management, cloud session, and disk workspace code. Resolved 12 bugs across session state management, disk file I/O paths, and cloud auto-save behavior.
+
+## Changes
+
+### Cloud Session & URL Hash Fixes (`js/cloud-share.js`)
+
+- **Fixed:** Cloud auto-save no longer overwrites all files to the same Firebase doc — added `resetCloudForFileSwitch()` to unbind cloud doc on file switch
+- **Fixed:** Boot-sequence content flicker — deferred localStorage restore when a share hash is present, eliminating restore → shared overwrite double render
+- **Fixed:** Autosave disk write now uses `writeFileToPath()` instead of flat `writeFile()` for correct subdirectory writes
+
+### File Switching & Shared Doc Cleanup (`js/workspace.js`)
+
+- **Fixed:** `wsCreateFile()`, `wsOpenFile()`, and `openDiskFile()` now call `clearCloudSession()` when leaving a shared doc, preventing stale `#id=...&k=...` URLs
+- **Fixed:** All three file-switch paths call `resetCloudForFileSwitch()` so each workspace file gets its own independent cloud doc
+- **Fixed:** `getFileContentAsync()` uses `readFileFromPath()` for correct subdirectory file reads
+- **Fixed:** `setFileContent()` uses `writeFileToPath()` for correct subdirectory disk writes
+- **Fixed:** `removeFileContent()` uses `deleteFileFromPath()` for correct subdirectory file deletes
+- **Fixed:** `wsConnectFolder()`, `wsReconnectFolder()`, `wsRefreshFromDisk()` all use `readFileFromPath()` for initial file loads
+- **Fixed:** `wsDisconnectFolder()` now calls `clearCloudSession()` to stop the cloud timer
+- **Fixed:** `setFileContent()` shows a user-facing toast when localStorage quota is exceeded instead of silently failing
+
+### Disk Reconnection UX (`js/disk-workspace.js`)
+
+- **Improved:** Replaced auto-dismissing toast with a persistent amber "Reconnect" sidebar banner when folder permission expires
+- **Added:** Clickable "Reconnect" button in sidebar that triggers `requestPermission()` directly
+
+### Reconnect Banner Styling (`css/workspace.css`)
+
+- **Added:** CSS for `.ws-reconnect-notice` and `.ws-reconnect-btn` (amber-themed persistent banner)
+
+### Collaborative Editing Plan (`upgradePlan/collaborative-editing.md`)
+
+- **Added:** Implementation plan for future real-time collaborative editing using Yjs + WebRTC + CodeMirror 6
+
+## Files Modified
+
+- `js/workspace.js` — 8 bug fixes across file CRUD, disk I/O, and cloud session management
+- `js/cloud-share.js` — 3 bug fixes + new `resetCloudForFileSwitch()` API
+- `js/disk-workspace.js` — Persistent reconnect banner replacing transient toast
+- `css/workspace.css` — Reconnect banner styles
+
+## Files Added
+
+- `upgradePlan/collaborative-editing.md` — Future collab editing implementation plan

css/workspace.css

@@ -382,6 +382,42 @@
     padding: 0;
 }
 
+/* --- Reconnect Notice (persistent sidebar banner) --- */
+.ws-reconnect-notice {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 8px 12px;
+    background: rgba(234, 179, 8, 0.1);
+    border-bottom: 1px solid rgba(234, 179, 8, 0.25);
+    font-size: 12px;
+    color: var(--text-color);
+    flex-shrink: 0;
+}
+.ws-reconnect-notice i {
+    color: #eab308;
+    font-size: 14px;
+    flex-shrink: 0;
+}
+.ws-reconnect-btn {
+    background: rgba(234, 179, 8, 0.2);
+    border: 1px solid rgba(234, 179, 8, 0.4);
+    color: #eab308;
+    font-size: 11px;
+    font-weight: 600;
+    padding: 3px 10px;
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.15s ease;
+    margin-left: auto;
+    white-space: nowrap;
+    font-family: inherit;
+}
+.ws-reconnect-btn:hover {
+    background: rgba(234, 179, 8, 0.35);
+    border-color: #eab308;
+}
+
 /* Folder label in header */
 #ws-folder-label {
     overflow: hidden;

js/cloud-share.js

@@ -115,7 +115,7 @@
             if (M.wsDiskMode && M._disk && M._disk.isConnected() && M.wsActiveFileId) {
                 var file = M._wsFindFileById ? M._wsFindFileById(M.wsActiveFileId) : null;
                 if (file) {
-                    M._disk.writeFile(file.name, M.markdownEditor.value).then(function () {
+                    M._disk.writeFileToPath(file.name, M.markdownEditor.value).then(function () {
                         showAutosaveIndicator('💾 Saved to disk');
                     }).catch(function (e) {
                         console.warn('Disk autosave failed:', e);
@@ -185,6 +185,7 @@
         var content = M.markdownEditor.value;
         if (!content.trim() || content === lastCloudContent) { cloudSaveDirty = false; return; }
         if (M.markdownEditor.readOnly) return;
+        // Don't auto-save if we're on someone else's shared URL and haven't established our own cloud doc
         var hash = window.location.hash;
         if (hash && (hash.includes('id=') || hash.includes('d=')) && !localStorage.getItem(CLOUD_DOC_KEY)) return;
         try {
@@ -383,6 +384,24 @@
     }
     M.clearCloudSession = clearCloudSession;
 
+    /**
+     * Reset cloud state for file switching (lighter than clearCloudSession).
+     * Each workspace file should get its own cloud doc — clear the current
+     * cloud doc binding so the next auto-save creates a fresh one.
+     */
+    function resetCloudForFileSwitch() {
+        localStorage.removeItem(CLOUD_DOC_KEY);
+        localStorage.removeItem(CLOUD_KEY_KEY);
+        localStorage.removeItem(CLOUD_WT_KEY);
+        lastCloudContent = '';
+        cloudSaveDirty = false;
+        // Clear hash so it doesn't show stale cloud doc URL
+        if (window.location.hash) {
+            window.history.replaceState({}, document.title, window.location.pathname);
+        }
+    }
+    M.resetCloudForFileSwitch = resetCloudForFileSwitch;
+
     document.getElementById('shared-banner-edit').addEventListener('click', function () {
         clearCloudSession();
         M.setViewMode('split');
@@ -692,14 +711,18 @@
     }
 
     // --- Restore Auto-Saved Content or Load Default ---
-    var wasRestored = restoreFromLocalStorage();
-    if (wasRestored) {
-        M.renderMarkdown();
-    } else if (!window.location.hash || (!window.location.hash.includes('d=') && !window.location.hash.includes('id='))) {
-        // No autosave and no share link — load Feature Showcase as default
-        if (M.getDefaultContent) {
-            M.markdownEditor.value = M.getDefaultContent();
+    // Only restore if we are NOT loading a shared link (which will overwrite the editor anyway)
+    var hasShareHash = window.location.hash && (window.location.hash.includes('d=') || window.location.hash.includes('id='));
+    if (!hasShareHash) {
+        var wasRestored = restoreFromLocalStorage();
+        if (wasRestored) {
             M.renderMarkdown();
+        } else {
+            // No autosave and no share link — load Feature Showcase as default
+            if (M.getDefaultContent) {
+                M.markdownEditor.value = M.getDefaultContent();
+                M.renderMarkdown();
+            }
         }
     }
 

js/disk-workspace.js

@@ -379,7 +379,27 @@
                 // Successfully reconnected — load workspace from disk
                 if (M.wsReconnectFolder) M.wsReconnectFolder();
             } else if (result === 'needs-permission') {
-                M.showToast('Folder reconnection needs permission. Use the folder button to reconnect.', 'info');
+                // Show a persistent notice in the sidebar instead of a transient toast
+                var sidebar = document.getElementById('workspace-sidebar');
+                if (sidebar) {
+                    var notice = document.createElement('div');
+                    notice.className = 'ws-reconnect-notice';
+                    notice.innerHTML =
+                        '<i class="bi bi-folder-symlink"></i> ' +
+                        '<span>Folder access expired. </span>' +
+                        '<button id="ws-reconnect-btn" class="ws-reconnect-btn">Reconnect</button>';
+                    sidebar.insertBefore(notice, sidebar.querySelector('.ws-file-list'));
+                    document.getElementById('ws-reconnect-btn').addEventListener('click', function () {
+                        disk.requestPermission().then(function (granted) {
+                            if (granted) {
+                                notice.remove();
+                                if (M.wsReconnectFolder) M.wsReconnectFolder();
+                            } else {
+                                M.showToast('Permission denied. Try using Open Folder instead.', 'warning');
+                            }
+                        });
+                    });
+                }
             }
         });
     }

js/workspace.js

@@ -61,20 +61,24 @@
     function getFileContentAsync(id) {
         if (diskMode && M._disk && M._disk.isConnected()) {
             var file = findFileById(id);
-            if (file) return M._disk.readFile(file.name);
+            // Use readFileFromPath so subdirectory files (e.g. "notes/ideas.md") resolve correctly
+            if (file) return M._disk.readFileFromPath(file.name);
         }
         return Promise.resolve(getFileContent(id));
     }
 
     function setFileContent(id, content) {
         try {
             localStorage.setItem(FILE_PREFIX + id, content);
-        } catch (e) { console.warn('File save failed:', e); }
+        } catch (e) {
+            console.warn('File save failed:', e);
+            if (M.showToast) M.showToast('⚠️ Save failed — browser storage is full. Free space or connect a folder.', 'error');
+        }
         // Also write to disk when in disk mode
         if (diskMode && M._disk && M._disk.isConnected()) {
             var file = findFileById(id);
             if (file) {
-                M._disk.writeFile(file.name, content).catch(function (e) {
+                M._disk.writeFileToPath(file.name, content).catch(function (e) {
                     console.warn('Disk file write failed:', e);
                 });
             }
@@ -86,7 +90,7 @@
         if (diskMode && M._disk && M._disk.isConnected()) {
             var file = findFileById(id);
             if (file) {
-                M._disk.deleteFile(file.name).catch(function (e) {
+                M._disk.deleteFileFromPath(file.name).catch(function (e) {
                     console.warn('Disk file delete failed:', e);
                 });
             }
@@ -335,6 +339,10 @@
     function openDiskFile(entry) {
         if (!M._disk || !M._disk.isConnected()) return;
 
+        // If we were viewing a shared doc, break out of that session
+        if (M.isViewingSharedDoc) M.clearCloudSession();
+        // Reset cloud doc binding so each file gets its own cloud doc
+        else if (M.resetCloudForFileSwitch) M.resetCloudForFileSwitch();
         // Save current file
         M.wsSaveCurrent();
 
@@ -535,6 +543,10 @@
     M.wsDiskMode = false;
 
     M.wsCreateFile = function (name) {
+        // If we were viewing a shared doc, break out of that session
+        if (M.isViewingSharedDoc) M.clearCloudSession();
+        // Reset cloud doc binding so new file gets its own cloud doc
+        else if (M.resetCloudForFileSwitch) M.resetCloudForFileSwitch();
         // Save current document first
         M.wsSaveCurrent();
         var id = generateId();
@@ -572,6 +584,10 @@
         if (id === workspace.activeFileId) return;
         var file = findFileById(id);
         if (!file) return;
+        // If we were viewing a shared doc, break out of that session
+        if (M.isViewingSharedDoc) M.clearCloudSession();
+        // Reset cloud doc binding so each file gets its own cloud doc
+        else if (M.resetCloudForFileSwitch) M.resetCloudForFileSwitch();
         // Save current
         M.wsSaveCurrent();
         // Switch
@@ -802,7 +818,7 @@
             // Load active file content
             var activeFile = findFileById(workspace.activeFileId);
             if (activeFile) {
-                var content = await M._disk.readFile(activeFile.name);
+                var content = await M._disk.readFileFromPath(activeFile.name);
                 M.markdownEditor.value = content;
                 // Cache in localStorage
                 localStorage.setItem(FILE_PREFIX + workspace.activeFileId, content);
@@ -829,6 +845,8 @@
         if (!M._disk) return;
         // Save current to localStorage before disconnecting
         M.wsSaveCurrent();
+        // Stop cloud auto-save timer so it doesn't create unwanted cloud docs
+        if (M.clearCloudSession) M.clearCloudSession();
         await M._disk.disconnect();
         diskMode = false;
         M.wsDiskMode = false;
@@ -874,7 +892,7 @@
             // Reload active file content from disk
             var activeFile = findFileById(workspace.activeFileId);
             if (activeFile) {
-                var content = await M._disk.readFile(activeFile.name);
+                var content = await M._disk.readFileFromPath(activeFile.name);
                 M.markdownEditor.value = content;
                 localStorage.setItem(FILE_PREFIX + workspace.activeFileId, content);
                 M.renderMarkdown();
@@ -918,7 +936,7 @@
             saveWorkspace();
             var activeFile = findFileById(workspace.activeFileId);
             if (activeFile) {
-                var content = await M._disk.readFile(activeFile.name);
+                var content = await M._disk.readFileFromPath(activeFile.name);
                 M.markdownEditor.value = content;
                 localStorage.setItem(FILE_PREFIX + workspace.activeFileId, content);
                 M.renderMarkdown();