termdock 1.4.121 → 1.4.123

package/dist/server/routes/filesystem.js

@@ -18,6 +18,7 @@ import { deleteFilesystemFile } from '../utils/deleteFilesystemFile.js';
 import { inspectKicadBoardPoint } from '../utils/kicadBoardInspection.js';
 import { EdaPreviewCache, requestAcceptsEtag } from '../utils/edaPreviewCache.js';
 import { convertHeicPreview, HEIC_PREVIEW_MIME_TYPES, isHeicPreviewPath } from '../utils/heicPreview.js';
+import { getWatchErrorCode, enqueueLatestWatchEvent, inspectLinuxInotifyUsage, isWatchResourceExhaustion, minimizeRecursiveWatchRoots, WATCH_IGNORED_NAMES, WATCH_RESOURCE_BACKOFF_MS, } from '../utils/fileWatchPolicy.js';
 const router = Router();
 const MAX_FILE_SIZE = 1024 * 1024; // 1MB
 const MAX_IMAGE_PREVIEW_SIZE = 20 * 1024 * 1024; // 20MB
@@ -59,7 +60,77 @@ const FS_IO_LOG_NAME = 'fs-io.log';
 const activeDiffSlots = new Map();
 const activeIoSlots = new Map();
 const sharedWatchRegistry = new Map();
-const SHARED_WATCH_EVICT_DELAY_MS = 60_000;
+const SHARED_WATCH_EVICT_DELAY_MS = 5_000;
+const WATCH_STAT_CONCURRENCY = 8;
+let watchAdmissionBlockedUntil = 0;
+function countActiveSharedWatches() {
+    let count = 0;
+    for (const entry of sharedWatchRegistry.values()) {
+        if (entry.subscription || entry.inFlight)
+            count += 1;
+    }
+    return count;
+}
+function broadcastSharedWatchEvent(entry, event) {
+    for (const client of entry.clients) {
+        if (!client.closed)
+            client.enqueue(event);
+    }
+}
+function drainSharedWatchEvents(entry) {
+    if (entry.failure || entry.clients.size === 0)
+        return;
+    while (entry.statWorkers < WATCH_STAT_CONCURRENCY && entry.pendingEvents.size > 0) {
+        const next = entry.pendingEvents.entries().next().value;
+        if (!next)
+            return;
+        const [changedPath, eventType] = next;
+        entry.pendingEvents.delete(changedPath);
+        if (eventType === 'delete') {
+            broadcastSharedWatchEvent(entry, { type: 'deleted', path: changedPath });
+            continue;
+        }
+        const generation = entry.eventGeneration;
+        entry.statWorkers += 1;
+        void fs.promises.lstat(changedPath)
+            .then((stat) => {
+            if (entry.failure || generation !== entry.eventGeneration)
+                return;
+            broadcastSharedWatchEvent(entry, {
+                type: eventType === 'create' ? 'created' : 'updated',
+                path: changedPath,
+                entry: toFileEntry(changedPath, stat),
+            });
+        })
+            .catch(() => {
+            if (entry.failure || generation !== entry.eventGeneration)
+                return;
+            broadcastSharedWatchEvent(entry, { type: 'deleted', path: changedPath });
+        })
+            .finally(() => {
+            entry.statWorkers -= 1;
+            drainSharedWatchEvents(entry);
+        });
+    }
+}
+function enqueueSharedNativeEvents(rootPath, entry, events) {
+    if (entry.clients.size === 0)
+        return;
+    for (const event of events) {
+        const changedPath = path.resolve(event.path);
+        if (!isPathInside(rootPath, changedPath) || isIgnoredWatchPath(rootPath, changedPath))
+            continue;
+        if (enqueueLatestWatchEvent(entry.pendingEvents, changedPath, event.type, WATCH_EVENT_STORM_LIMIT) === 'overflow') {
+            entry.pendingEvents.clear();
+            entry.eventGeneration += 1;
+            broadcastSharedWatchEvent(entry, { type: 'rescan-required', path: rootPath, reason: 'event-storm' });
+            return;
+        }
+        // The latest event for one path wins. This turns save bursts and atomic
+        // editor renames into one stat operation instead of one operation/event.
+    }
+    drainSharedWatchEvents(entry);
+}
 function sharedWatchCallback(rootPath, entry) {
     return (error, events) => {
         if (entry.failure)
@@ -67,42 +138,35 @@ function sharedWatchCallback(rootPath, entry) {
         if (error) {
             entry.failure = error.message || 'watch-error';
             const reason = entry.failure;
-            for (const client of entry.clients) {
+            entry.pendingEvents.clear();
+            entry.eventGeneration += 1;
+            const resourceExhausted = isWatchResourceExhaustion(error);
+            if (resourceExhausted)
+                watchAdmissionBlockedUntil = Date.now() + WATCH_RESOURCE_BACKOFF_MS;
+            console.warn('[file-watch] Native subscription callback failed; degrading to manual refresh', {
+                rootPath,
+                code: getWatchErrorCode(error),
+                activeSubscriptions: countActiveSharedWatches(),
+                registrySize: sharedWatchRegistry.size,
+                resourceBackoffMs: resourceExhausted ? WATCH_RESOURCE_BACKOFF_MS : 0,
+                error: reason,
+            });
+            const failedSubscription = entry.subscription;
+            entry.subscription = null;
+            void failedSubscription?.unsubscribe().catch(() => undefined);
+            if (resourceExhausted) {
+                void inspectLinuxInotifyUsage().then((diagnostics) => {
+                    if (diagnostics)
+                        console.warn('[file-watch] Linux inotify usage after callback failure', diagnostics);
+                }).catch(() => undefined);
+            }
+            for (const client of [...entry.clients]) {
                 if (!client.closed)
-                    client.enqueue({ type: 'rescan-required', path: rootPath, reason });
+                    client.degrade(reason);
             }
             return;
         }
-        for (const event of events) {
-            const changedPath = path.resolve(event.path);
-            if (!isPathInside(rootPath, changedPath) || isIgnoredWatchPath(rootPath, changedPath))
-                continue;
-            if (event.type === 'delete') {
-                for (const client of entry.clients) {
-                    if (!client.closed)
-                        client.enqueue({ type: 'deleted', path: changedPath });
-                }
-                continue;
-            }
-            fs.promises.lstat(changedPath)
-                .then((stat) => {
-                const payload = {
-                    type: event.type === 'create' ? 'created' : 'updated',
-                    path: changedPath,
-                    entry: toFileEntry(changedPath, stat),
-                };
-                for (const client of entry.clients) {
-                    if (!client.closed)
-                        client.enqueue(payload);
-                }
-            })
-                .catch(() => {
-                for (const client of entry.clients) {
-                    if (!client.closed)
-                        client.enqueue({ type: 'deleted', path: changedPath });
-                }
-            });
-        }
+        enqueueSharedNativeEvents(rootPath, entry, events);
     };
 }
 async function acquireSharedWatch(rootPath, client) {
@@ -115,6 +179,10 @@ async function acquireSharedWatch(rootPath, client) {
             clients: new Set(),
             inFlight: null,
             evictTimer: null,
+            pendingEvents: new Map(),
+            statWorkers: 0,
+            eventGeneration: 0,
+            needsRescanOnAttach: false,
         };
         sharedWatchRegistry.set(rootPath, entry);
     }
@@ -124,11 +192,32 @@ async function acquireSharedWatch(rootPath, client) {
     }
     entry.refs += 1;
     entry.clients.add(client);
+    if (entry.needsRescanOnAttach) {
+        entry.needsRescanOnAttach = false;
+        client.enqueue({ type: 'rescan-required', path: rootPath, reason: 'reconnected' });
+    }
     if (entry.failure)
         return null;
     if (entry.subscription)
         return rootPath;
     if (!entry.inFlight) {
+        const now = Date.now();
+        const activeSubscriptions = countActiveSharedWatches();
+        if (now < watchAdmissionBlockedUntil) {
+            entry.failure = `native watcher admission paused for ${Math.ceil((watchAdmissionBlockedUntil - now) / 1000)}s after resource exhaustion`;
+            console.warn('[file-watch] Subscription skipped while resource backoff is active', {
+                rootPath,
+                activeSubscriptions,
+                registrySize: sharedWatchRegistry.size,
+            });
+            return null;
+        }
+        const startedAt = Date.now();
+        console.info('[file-watch] Starting native subscription', {
+            rootPath,
+            activeSubscriptions: activeSubscriptions + 1,
+            registrySize: sharedWatchRegistry.size,
+        });
         entry.inFlight = watcher.subscribe(rootPath, sharedWatchCallback(rootPath, entry), {
             ignore: Array.from(WATCH_IGNORED_NAMES).map((name) => `**/${name}/**`),
         })
@@ -141,12 +230,36 @@ async function acquireSharedWatch(rootPath, client) {
                 return null;
             }
             current.subscription = subscription;
+            console.info('[file-watch] Native subscription ready', {
+                rootPath,
+                scanDurationMs: Date.now() - startedAt,
+                activeSubscriptions: countActiveSharedWatches(),
+                registrySize: sharedWatchRegistry.size,
+            });
             return subscription;
         })
             .catch((error) => {
             const current = sharedWatchRegistry.get(rootPath);
             if (current)
                 current.failure = error instanceof Error ? error.message : String(error);
+            const resourceExhausted = isWatchResourceExhaustion(error);
+            if (resourceExhausted)
+                watchAdmissionBlockedUntil = Date.now() + WATCH_RESOURCE_BACKOFF_MS;
+            console.warn('[file-watch] Native subscription failed; degrading to manual refresh', {
+                rootPath,
+                code: getWatchErrorCode(error),
+                scanDurationMs: Date.now() - startedAt,
+                activeSubscriptions: countActiveSharedWatches(),
+                registrySize: sharedWatchRegistry.size,
+                resourceBackoffMs: resourceExhausted ? WATCH_RESOURCE_BACKOFF_MS : 0,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (resourceExhausted) {
+                void inspectLinuxInotifyUsage().then((diagnostics) => {
+                    if (diagnostics)
+                        console.warn('[file-watch] Linux inotify usage after resource exhaustion', diagnostics);
+                }).catch(() => undefined);
+            }
             return null;
         })
             .finally(() => {
@@ -168,6 +281,13 @@ function releaseSharedWatch(rootPath, client) {
     entry.refs -= 1;
     if (entry.refs > 0)
         return;
+    entry.needsRescanOnAttach = true;
+    entry.pendingEvents.clear();
+    entry.eventGeneration += 1;
+    if (!entry.subscription && !entry.inFlight) {
+        sharedWatchRegistry.delete(rootPath);
+        return;
+    }
     if (entry.evictTimer)
         clearTimeout(entry.evictTimer);
     entry.evictTimer = setTimeout(() => {
@@ -414,9 +534,6 @@ function compareDirents(a, b) {
         return 1;
     return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 }
-const WATCH_IGNORED_NAMES = new Set([
-    '.git', 'node_modules', 'dist', 'build', '.next', '.nuxt', '.turbo', 'coverage', 'target', '.gradle', '.idea', '.DS_Store',
-]);
 const NESTED_GIT_DISCOVERY_IGNORED_NAMES = new Set([
     '.git', 'node_modules', 'dist', 'build', '.next', '.nuxt', '.turbo', 'coverage', 'target', '.gradle', '.idea', '.DS_Store',
     '.cache', '.parcel-cache', '.yarn', '.pnpm-store', 'vendor',
@@ -1353,11 +1470,12 @@ function toFileEntry(entryPath, stat, isSymlink = false) {
         path: entryPath,
         type: stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : 'file',
         isSymlink,
+        modified: stat.mtime.toISOString(),
     };
 }
-async function toDirectoryEntry(dir, dirent) {
+async function toDirectoryEntry(dir, dirent, includeModified = false) {
     const entryPath = path.join(dir, dirent.name);
-    if (!dirent.isSymbolicLink()) {
+    if (!dirent.isSymbolicLink() && !includeModified) {
         return {
             name: dirent.name,
             path: entryPath,
@@ -1369,19 +1487,39 @@ async function toDirectoryEntry(dir, dirent) {
         return {
             name: dirent.name,
             path: entryPath,
-            type: stat.isDirectory() ? 'directory' : 'symlink',
-            isSymlink: true,
+            type: stat.isDirectory() ? 'directory' : dirent.isSymbolicLink() ? 'symlink' : 'file',
+            isSymlink: dirent.isSymbolicLink() || undefined,
+            modified: includeModified ? stat.mtime.toISOString() : undefined,
         };
     }
     catch {
         return {
             name: dirent.name,
             path: entryPath,
-            type: 'symlink',
-            isSymlink: true,
+            type: dirent.isDirectory() ? 'directory' : dirent.isSymbolicLink() ? 'symlink' : 'file',
+            isSymlink: dirent.isSymbolicLink() || undefined,
         };
     }
 }
+async function loadDirectoryEntriesWithModified(dir, dirents, signal) {
+    const entries = [];
+    const batchSize = 64;
+    for (let offset = 0; offset < dirents.length; offset += batchSize) {
+        throwIfAborted(signal, 'fs.list');
+        entries.push(...await Promise.all(dirents.slice(offset, offset + batchSize).map((dirent) => toDirectoryEntry(dir, dirent, true))));
+    }
+    return entries;
+}
+function compareDirectoryEntriesByModified(a, b) {
+    if (a.type === 'directory' && b.type !== 'directory')
+        return -1;
+    if (a.type !== 'directory' && b.type === 'directory')
+        return 1;
+    const modifiedDelta = Date.parse(b.modified ?? '') - Date.parse(a.modified ?? '');
+    if (Number.isFinite(modifiedDelta) && modifiedDelta !== 0)
+        return modifiedDelta;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
 function isIgnoredWatchPath(rootPath, candidatePath) {
     const relative = path.relative(rootPath, candidatePath);
     if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
@@ -2378,13 +2516,18 @@ router.get('/list', async (req, res) => {
                 throw new Error('Path is not a directory');
             }
             const showHidden = req.query.showHidden === 'true';
+            const sortMode = req.query.sort === 'modified' ? 'modified' : 'name';
             const allEntries = await fs.promises.readdir(resolvedPath, { withFileTypes: true });
             throwIfAborted(controller.signal, 'fs.list');
             const visibleDirents = allEntries.filter(dirent => showHidden || !dirent.name.startsWith('.'));
-            const returnedDirents = visibleDirents
-                .sort(compareDirents)
-                .slice(0, MAX_DIRECTORY_ENTRIES);
-            const entries = await Promise.all(returnedDirents.map((dirent) => toDirectoryEntry(resolvedPath, dirent)));
+            const entries = sortMode === 'modified'
+                ? (await loadDirectoryEntriesWithModified(resolvedPath, visibleDirents, controller.signal))
+                    .sort(compareDirectoryEntriesByModified)
+                    .slice(0, MAX_DIRECTORY_ENTRIES)
+                : await Promise.all(visibleDirents
+                    .sort(compareDirents)
+                    .slice(0, MAX_DIRECTORY_ENTRIES)
+                    .map((dirent) => toDirectoryEntry(resolvedPath, dirent)));
             throwIfAborted(controller.signal, 'fs.list');
             return { resolvedPath, entries, total: visibleDirents.length };
         })(), FS_ROUTE_TIMEOUT_MS, 'Directory listing took too long. The folder may be on a slow disk or network mount.', 'FS_LIST_TIMEOUT');
@@ -2410,20 +2553,21 @@ router.get('/watch', async (req, res) => {
     const rootsParam = req.query.roots;
     const rawRoots = (Array.isArray(rootsParam) ? rootsParam : typeof rootsParam === 'string' ? rootsParam.split('|') : [])
         .filter((root) => typeof root === 'string');
-    const roots = [];
+    const validatedRoots = [];
     for (const rawRoot of rawRoots) {
         if (!rawRoot)
             continue;
         try {
             const resolved = await pathValidator.validatePathAsync(rawRoot);
             const stat = await fs.promises.stat(resolved);
-            if (stat.isDirectory() && !roots.includes(resolved))
-                roots.push(resolved);
+            if (stat.isDirectory() && !validatedRoots.includes(resolved))
+                validatedRoots.push(resolved);
         }
         catch {
             // Ignore invalid watch roots; the visible tree will still work via manual list requests.
         }
     }
+    const roots = minimizeRecursiveWatchRoots(validatedRoots);
     if (roots.length === 0) {
         res.status(400).json({ error: 'No valid roots to watch' });
         return;
@@ -2435,6 +2579,21 @@ router.get('/watch', async (req, res) => {
     let pending = [];
     let flushTimer = null;
     const attachedRoots = new Map();
+    // Register cleanup before the first native subscription starts. A recursive
+    // initial scan can take seconds on a large repository; the browser may abort
+    // during that await when the user switches files or roots. Registering this
+    // only after attachRoot() leaked the pending subscription and its reference.
+    const closeWatchStream = () => {
+        if (closed)
+            return;
+        closed = true;
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        for (const [rootPath, client] of attachedRoots) {
+            releaseSharedWatch(rootPath, client);
+        }
+    };
+    res.once('close', closeWatchStream);
     const writeEvent = (type, payload) => {
         if (closed || res.destroyed)
             return;
@@ -2463,28 +2622,43 @@ router.get('/watch', async (req, res) => {
         }
     };
     writeEvent('ready', { roots });
+    console.info('[file-watch] Stream ready', {
+        requestedRoots: rawRoots.length,
+        validatedRoots: validatedRoots.length,
+        subscribedRoots: roots.length,
+        collapsedOverlappingRoots: validatedRoots.length - roots.length,
+        activeSubscriptions: countActiveSharedWatches(),
+        registrySize: sharedWatchRegistry.size,
+    });
     const attachRoot = async (rootPath) => {
-        const client = { closed: false, enqueue };
+        if (closed)
+            return;
+        const client = {
+            closed: false,
+            enqueue,
+            degrade: (reason) => {
+                if (closed)
+                    return;
+                enqueue({ type: 'rescan-required', path: rootPath, reason });
+                flush();
+                if (!res.writableEnded)
+                    res.end();
+            },
+        };
         attachedRoots.set(rootPath, client);
         const ok = await acquireSharedWatch(rootPath, client);
         if (closed)
             return;
         if (!ok) {
             const reason = sharedWatchRegistry.get(rootPath)?.failure ?? 'watch-unavailable';
-            enqueue({ type: 'rescan-required', path: rootPath, reason });
+            client.degrade(reason);
         }
     };
     for (const rootPath of roots) {
+        if (closed)
+            break;
         await attachRoot(rootPath);
     }
-    req.on('close', () => {
-        closed = true;
-        if (flushTimer)
-            clearTimeout(flushTimer);
-        for (const [rootPath, client] of attachedRoots) {
-            releaseSharedWatch(rootPath, client);
-        }
-    });
 });
 router.get('/cancel-slot', (req, res) => {
     const requestSlotId = typeof req.query.requestSlotId === 'string' ? req.query.requestSlotId : undefined;

package/dist/server/routes/terminal.js

@@ -14,9 +14,10 @@ import { getPtyHostManager } from '../ptyhost/manager.js';
 import { pathValidator } from '../utils/pathValidator.js';
 import { TERMINAL, TMUX } from '../config.js';
 import { localAccessManager } from '../utils/localAccess.js';
-import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, setRunningSessionButtonEnabledSetting, } from '../utils/settings.js';
+import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, setRunningSessionButtonEnabledSetting, getFileSortModesSetting, setFileSortModesSetting, setFileSortModeSetting, } from '../utils/settings.js';
 import { loadContextDraft, saveContextDraft } from '../utils/contextDraft.js';
 import { getOnboardingServerUrl } from '../onboardingServer.js';
+import { inspectLinuxInotifyUsage, isWatchResourceExhaustion } from '../utils/fileWatchPolicy.js';
 import { getFocusSequence, removeClientFocusState, scanFocusTrackingMode, setClientFocusState, } from '../utils/tmuxFocus.js';
 import { extractProgramLabelFromArgs, normalizeProgramName, normalizeTmuxMetadataProgram, selectTmuxForegroundProgram, tmuxMetadataChanged, } from '../utils/tmuxProgramDetection.js';
 import { agentBySlug, buildResumeCommand, detectAgentFromCommand, inferResumeSessionId, listAgents, } from '../agent/registry.js';
@@ -457,6 +458,15 @@ function scheduleReloadGlobalSessionState() {
     globalSessionStateReloadTimer.unref?.();
 }
 async function watchGlobalSessionStateFile() {
+    const reportFailure = (message, error) => {
+        console.warn(message, getErrorMessage(error));
+        if (!isWatchResourceExhaustion(error))
+            return;
+        void inspectLinuxInotifyUsage().then((diagnostics) => {
+            if (diagnostics)
+                console.warn('[session-persist] Linux inotify usage after watcher failure:', diagnostics);
+        }).catch(() => undefined);
+    };
     try {
         const dir = path.dirname(GLOBAL_SESSION_STATE_FILE);
         await fs.promises.mkdir(dir, { recursive: true });
@@ -468,11 +478,11 @@ async function watchGlobalSessionStateFile() {
             scheduleReloadGlobalSessionState();
         });
         globalSessionStateWatcher.on('error', (error) => {
-            console.warn('[session-persist] Global state watcher failed:', getErrorMessage(error));
+            reportFailure('[session-persist] Global state watcher failed:', error);
         });
     }
     catch (error) {
-        console.warn('[session-persist] Failed to watch global state file:', getErrorMessage(error));
+        reportFailure('[session-persist] Failed to watch global state file:', error);
     }
 }
 function schedulePersistGlobalState() {
@@ -5566,6 +5576,7 @@ async function getSettingsPayload() {
         autoRenamePromptPayloadChars: getAutoRenamePromptPayloadCharsSetting(),
         newSessionAgentSlug: getNewSessionAgentSlugSetting(),
         runningSessionButtonEnabled: getRunningSessionButtonEnabledSetting(),
+        fileSortModes: getFileSortModesSetting(),
         localAccess: {
             ...localAccess,
             interfaces,
@@ -5677,6 +5688,21 @@ router.put('/settings', async (req, res) => {
     if (typeof body.runningSessionButtonEnabled === 'boolean') {
         setRunningSessionButtonEnabledSetting(body.runningSessionButtonEnabled);
     }
+    if (body.fileSortModes && typeof body.fileSortModes === 'object' && !Array.isArray(body.fileSortModes)) {
+        setFileSortModesSetting(body.fileSortModes);
+    }
+    if (body.fileSortMode && typeof body.fileSortMode === 'object') {
+        const preference = body.fileSortMode;
+        const validPath = typeof preference.path === 'string'
+            && preference.path.length > 0
+            && preference.path.length <= 4096
+            && (preference.path.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(preference.path));
+        if (!validPath || (preference.mode !== 'name' && preference.mode !== 'modified')) {
+            res.status(400).json({ error: 'Invalid file sort preference', code: 'FILE_SORT_MODE_INVALID' });
+            return;
+        }
+        setFileSortModeSetting(preference.path, preference.mode);
+    }
     if (body.localAccess && typeof body.localAccess === 'object') {
         const localAccessBody = body.localAccess;
         if (localAccessBody.reset === true) {

package/dist/server/utils/fileWatchPolicy.js

@@ -0,0 +1,136 @@
+import path from 'path';
+import fs from 'fs';
+export const WATCH_IGNORED_NAMES = new Set([
+    '.git', 'node_modules', 'dist', 'build', '.next', '.nuxt', '.turbo', 'coverage', 'target', '.gradle', '.idea', '.DS_Store',
+]);
+export const WATCH_RESOURCE_BACKOFF_MS = 60_000;
+export function enqueueLatestWatchEvent(pending, eventPath, eventType, maxPending) {
+    if (!pending.has(eventPath) && pending.size >= maxPending)
+        return 'overflow';
+    pending.set(eventPath, eventType);
+    return 'queued';
+}
+function isSameOrDescendant(parentPath, candidatePath) {
+    const relative = path.relative(parentPath, candidatePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+/**
+ * Recursive watchers already cover every descendant. Keep only the shallowest
+ * roots so expanding a folder inside an already watched folder cannot allocate
+ * another overlapping native watcher.
+ */
+export function minimizeRecursiveWatchRoots(roots) {
+    const uniqueRoots = [...new Set(roots.map((root) => path.resolve(root)))];
+    uniqueRoots.sort((a, b) => a.split(path.sep).length - b.split(path.sep).length || a.localeCompare(b));
+    const minimal = [];
+    for (const root of uniqueRoots) {
+        if (!minimal.some((parent) => isSameOrDescendant(parent, root)))
+            minimal.push(root);
+    }
+    return minimal;
+}
+export function getWatchErrorCode(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const code = error.code;
+    return typeof code === 'string' ? code.toUpperCase() : null;
+}
+export function isWatchResourceExhaustion(error) {
+    const code = getWatchErrorCode(error);
+    if (code === 'EMFILE' || code === 'ENFILE' || code === 'ENOSPC')
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b(?:EMFILE|ENFILE|ENOSPC)\b|too many open files|inotify/i.test(message);
+}
+export function countInotifyWatchDescriptors(fdInfo) {
+    return fdInfo.split('\n').filter((line) => line.startsWith('inotify wd:')).length;
+}
+/** Best-effort Linux-only snapshot. Call only on watcher failures, never on the hot path. */
+export async function inspectLinuxInotifyUsage() {
+    if (process.platform !== 'linux' || typeof process.getuid !== 'function')
+        return null;
+    const uid = process.getuid();
+    let partial = false;
+    let maxUserInstances = null;
+    let maxUserWatches = null;
+    try {
+        const raw = await fs.promises.readFile('/proc/sys/fs/inotify/max_user_instances', 'utf8');
+        const parsed = Number.parseInt(raw.trim(), 10);
+        if (Number.isFinite(parsed))
+            maxUserInstances = parsed;
+    }
+    catch {
+        partial = true;
+    }
+    try {
+        const raw = await fs.promises.readFile('/proc/sys/fs/inotify/max_user_watches', 'utf8');
+        const parsed = Number.parseInt(raw.trim(), 10);
+        if (Number.isFinite(parsed))
+            maxUserWatches = parsed;
+    }
+    catch {
+        partial = true;
+    }
+    let procEntries;
+    try {
+        procEntries = await fs.promises.readdir('/proc', { withFileTypes: true });
+    }
+    catch {
+        return { maxUserInstances, maxUserWatches, observedUserInstances: 0, observedUserWatches: 0, topConsumers: [], partial: true };
+    }
+    const consumers = [];
+    for (const procEntry of procEntries) {
+        if (!procEntry.isDirectory() || !/^\d+$/.test(procEntry.name))
+            continue;
+        const pid = Number(procEntry.name);
+        const procPath = `/proc/${procEntry.name}`;
+        try {
+            if ((await fs.promises.stat(procPath)).uid !== uid)
+                continue;
+            const fdEntries = await fs.promises.readdir(`${procPath}/fd`);
+            let instances = 0;
+            let watches = 0;
+            for (const fd of fdEntries) {
+                try {
+                    if ((await fs.promises.readlink(`${procPath}/fd/${fd}`)) !== 'anon_inode:inotify')
+                        continue;
+                    instances += 1;
+                    try {
+                        watches += countInotifyWatchDescriptors(await fs.promises.readFile(`${procPath}/fdinfo/${fd}`, 'utf8'));
+                    }
+                    catch {
+                        partial = true;
+                    }
+                }
+                catch {
+                    // Processes and descriptors can disappear while /proc is sampled.
+                }
+            }
+            if (instances === 0)
+                continue;
+            let command = procEntry.name;
+            try {
+                const rawCommand = await fs.promises.readFile(`${procPath}/comm`, 'utf8');
+                command = rawCommand.trim() || command;
+            }
+            catch {
+                partial = true;
+            }
+            consumers.push({ pid, command, instances, watches });
+        }
+        catch (error) {
+            const code = getWatchErrorCode(error);
+            if (code !== 'ENOENT' && code !== 'ESRCH')
+                partial = true;
+        }
+    }
+    consumers.sort((a, b) => b.watches - a.watches || b.instances - a.instances || a.pid - b.pid);
+    return {
+        maxUserInstances,
+        maxUserWatches,
+        observedUserInstances: consumers.reduce((total, item) => total + item.instances, 0),
+        observedUserWatches: consumers.reduce((total, item) => total + item.watches, 0),
+        topConsumers: consumers.slice(0, 8),
+        partial,
+    };
+}