specrails-desktop 2.36.0 → 2.42.2

package/server/dist/file-summary-manager.js

@@ -36,9 +36,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileSummaryManager = exports.SUMMARY_MAX_LENGTH = void 0;
+exports.FileSummaryManager = exports.WATCH_DEBOUNCE_MS = exports.SUMMARY_MAX_LENGTH = exports.CURRENT_PROMPT_VERSION = void 0;
 exports.isValidSummaryPayload = isValidSummaryPayload;
+exports.isSummaryMetadataStale = isSummaryMetadataStale;
 exports.summariesDir = summariesDir;
+exports.repositorySummaryRoot = repositorySummaryRoot;
 exports.pathHash = pathHash;
 exports.summaryFilePath = summaryFilePath;
 exports.computeFileHash = computeFileHash;
@@ -46,6 +48,7 @@ exports.readSummary = readSummary;
 exports.writeSummary = writeSummary;
 exports.ensureGitignoreLine = ensureGitignoreLine;
 exports.sweepOrphans = sweepOrphans;
+exports.resolveWatchEngine = resolveWatchEngine;
 exports.__resetDesktopSummaryStateForTests = __resetDesktopSummaryStateForTests;
 const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
@@ -58,7 +61,7 @@ const file_summary_v1_json_1 = __importDefault(require("./schemas/file-summary.v
 const SUMMARIES_REL = path.join('.specrails', 'file-summaries');
 // Current summary prompt version. Bump when buildSystemPrompt changes materially
 // so existing summaries are treated as stale and regenerated on next request.
-const CURRENT_PROMPT_VERSION = 1;
+exports.CURRENT_PROMPT_VERSION = 2;
 // Defensive bound on the per-job counter map so it cannot grow without limit
 // across a long-lived app session (the per-job cap is best-effort).
 const MAX_JOB_COUNTERS = 2000;
@@ -97,17 +100,61 @@ function getSummaryValidator() {
 /** True when `payload` conforms to file-summary.v1.json (with the maxLength
  *  bound on `summary`). Exported so callers/tests can pre-validate. */
 function isValidSummaryPayload(payload) {
-    return getSummaryValidator()(payload) === true;
+    if (getSummaryValidator()(payload) !== true)
+        return false;
+    const summary = payload;
+    return summary.summary.trim().length > 0 && Number.isFinite(Date.parse(summary.generatedAt));
+}
+/** Legacy caches remain readable, but new prompts/language require regeneration. */
+function isSummaryMetadataStale(summary, language) {
+    return summary.language !== language || summary.generatedBy.promptVersion !== exports.CURRENT_PROMPT_VERSION;
 }
 function summariesDir(projectPath) {
     return path.join(projectPath, SUMMARIES_REL);
 }
+/** Secondary artifacts belong to the logical project's workspace, never to a
+ * member's own Core registry/backlog. The primary keeps its historical layout. */
+function repositorySummaryRoot(artifactRoot, repository) {
+    return repository.isPrimary ? artifactRoot : path.join(artifactRoot, '.specrails', 'repository-context', pathHash(repository.id));
+}
+function repositoryKey(projectId, repositoryId) {
+    return JSON.stringify([projectId, repositoryId ?? null]);
+}
 function pathHash(relPath) {
     return (0, crypto_1.createHash)('sha256').update(Buffer.from(relPath, 'utf8')).digest('hex');
 }
 function summaryFilePath(projectPath, relPath) {
     return path.join(summariesDir(projectPath), `${pathHash(relPath)}.json`);
 }
+/** Revalidate the queued target and bound reads before handing any bytes to AI. */
+function readSourceSnapshot(projectPath, relPath) {
+    const root = fs.realpathSync(projectPath);
+    const absolute = fs.realpathSync(path.resolve(root, relPath));
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative))
+        throw new Error('Source escapes repository');
+    const fd = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const maximum = 2 * 1024 * 1024;
+        const metadata = fs.fstatSync(fd);
+        if (!metadata.isFile() || metadata.size > maximum)
+            throw new Error('Source is not a supported file');
+        const bytes = Buffer.alloc(Math.min(maximum + 1, metadata.size + 1));
+        let length = 0;
+        while (length < bytes.length) {
+            const read = fs.readSync(fd, bytes, length, bytes.length - length, null);
+            if (!read)
+                break;
+            length += read;
+        }
+        if (length > metadata.size || length > maximum || bytes.subarray(0, Math.min(length, 8192)).includes(0))
+            throw new Error('Source changed size or is binary');
+        return bytes.subarray(0, length);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 async function computeFileHash(absolutePath) {
     // Use streaming hash so very large files do not balloon memory.
     return await new Promise((resolve, reject) => {
@@ -121,12 +168,15 @@ async function computeFileHash(absolutePath) {
 function readSummary(projectPath, relPath) {
     const file = summaryFilePath(projectPath, relPath);
     try {
+        const metadata = fs.lstatSync(file);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 128 * 1024)
+            return null;
         const raw = fs.readFileSync(file, 'utf8');
         const parsed = JSON.parse(raw);
         // Validate against file-summary.v1.json. A corrupt / hand-edited /
         // cross-version / oversized summary is treated as ABSENT (null) instead of
         // being trusted and surfaced verbatim — so the next request regenerates it.
-        if (!isValidSummaryPayload(parsed))
+        if (!isValidSummaryPayload(parsed) || parsed.path !== relPath)
             return null;
         return parsed;
     }
@@ -142,7 +192,7 @@ function writeSummary(summaryRoot, relPath, payload,
 appendGitignore = true) {
     // Reject a non-conformant payload before it ever lands on disk so the
     // documented "schema validated" invariant is real, not aspirational.
-    if (!isValidSummaryPayload(payload)) {
+    if (!isValidSummaryPayload(payload) || payload.path !== relPath) {
         throw new Error('writeSummary: payload failed file-summary.v1 schema validation');
     }
     const dir = summariesDir(summaryRoot);
@@ -225,6 +275,36 @@ sourceRoot) {
     }
     return { deleted, remaining };
 }
+/** Trailing debounce applied to source-change events before the stale check. */
+exports.WATCH_DEBOUNCE_MS = 200;
+/** Errno codes meaning the watcher is consuming a process-wide resource it can
+ *  no longer get (kqueue file descriptors on macOS, inotify watches on Linux).
+ *  Keeping such a watcher alive keeps the leak — and, before this guard, an
+ *  unhandled `error` event on the recursive watcher took the whole server down
+ *  (`Error: EMFILE: too many open files, watch`). Close + degrade instead. */
+const WATCHER_EXHAUSTION_CODES = new Set(['EMFILE', 'ENFILE', 'ENOSPC']);
+/**
+ * Pick the source-watch engine for a platform.
+ *
+ * macOS and Windows get the kernel's own recursive watch —
+ * `fs.watch(dir, { recursive: true })` = FSEvents / ReadDirectoryChangesW —
+ * which costs ONE handle for the whole tree. chokidar ≥ 4 dropped fsevents and
+ * watches every file with its own `fs.watch`; on macOS that is one kqueue fd
+ * PER FILE, so any repo past the ~10k-fd limit blew the process up with
+ * `EMFILE: too many open files, watch`. Linux keeps chokidar: inotify watches
+ * are not fds, and chokidar's `ignored` pruning keeps `node_modules` / build
+ * trees out of the watch set (Node's own recursive implementation on Linux
+ * walks and watches everything, `node_modules` included).
+ */
+function resolveWatchEngine(platform = process.platform) {
+    return platform === 'darwin' || platform === 'win32' ? 'native' : 'chokidar';
+}
+function errnoCode(err) {
+    return err?.code;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 // App-wide concurrency is shared across EVERY FileSummaryManager instance.
 // Production constructs one manager per project (each with its own db/broadcast/
 // generate), so a per-instance counter would only ever cap per-project. This
@@ -271,9 +351,9 @@ class FileSummaryManager {
     _disposed = false;
     // Per-project SUPERSET of relPaths that have a summary on disk. Seeded from
     // the summaries dir at attachWatcher and only ever added to (on write), so a
-    // path absent from the set provably has no summary — letting the chokidar
-    // 'change' handler skip the readSummary disk hit for the common no-summary
-    // file. A stale entry (after sweep) just costs one harmless failed read.
+    // path absent from the set provably has no summary — letting the watcher's
+    // change funnel skip the disk hits for the common no-summary file. A stale
+    // entry (after sweep) just costs one harmless failed read.
     knownSummaries = new Map();
     // Tracks pending generation promises so flush() can await them in tests.
     pending = new Set();
@@ -289,23 +369,26 @@ class FileSummaryManager {
     // NOT async: returning the in-flight promise verbatim is what makes the dedupe
     // a true coalesce (the second caller gets the SAME promise, not a wrapper).
     enqueue(req) {
+        if (this._disposed)
+            return Promise.resolve('skipped:not-found');
         // Per-(project,relPath) in-flight dedupe: a second enqueue for the same file
         // while one is still running coalesces onto the first promise, so the
         // provider is spawned once and ai_invocations is billed once (fixes
         // concurrent-regenerate double-billing across tabs/clients).
-        const dedupeKey = `${req.projectId}:${req.relPath}`;
+        const dedupeKey = JSON.stringify([req.projectId, req.repositoryId ?? null, req.relPath]);
         const existing = this.inFlightByKey.get(dedupeKey);
         if (existing)
             return existing;
-        const p = this._enqueueInner(req);
-        this.inFlightByKey.set(dedupeKey, p);
-        void p.catch(() => undefined).finally(() => {
+        const p = this._enqueueInner(req).finally(() => {
             if (this.inFlightByKey.get(dedupeKey) === p)
                 this.inFlightByKey.delete(dedupeKey);
         });
+        this.inFlightByKey.set(dedupeKey, p);
         return p;
     }
     async _enqueueInner(req) {
+        if (this._disposed)
+            return 'skipped:not-found';
         const absolutePath = path.join(req.projectPath, req.relPath);
         // Step 1: file readability check.
         let newHash;
@@ -316,8 +399,12 @@ class FileSummaryManager {
                 return 'skipped:not-found';
             }
             newHash = await computeFileHash(absolutePath);
+            if (this._disposed)
+                return 'skipped:not-found';
         }
         catch {
+            if (this._disposed)
+                return 'skipped:not-found';
             this.emitSkipped(req, 'not-found');
             return 'skipped:not-found';
         }
@@ -333,8 +420,8 @@ class FileSummaryManager {
             existing &&
             existing.fileHash === newHash &&
             existing.language === currentLang &&
-            existing.generatedBy?.promptVersion === CURRENT_PROMPT_VERSION) {
-            this.deps.broadcast(buildSummaryUpdated(req.projectId, existing, false));
+            existing.generatedBy?.promptVersion === exports.CURRENT_PROMPT_VERSION) {
+            this.deps.broadcast(buildSummaryUpdated(req.projectId, existing, false, req.repositoryId));
             return 'skipped:hash';
         }
         // Step 3: per-job cap — PRE-CHECK ONLY. The counter is incremented in pump()
@@ -361,21 +448,28 @@ class FileSummaryManager {
                 return 'skipped:budget';
             }
         }
-        // Step 5: enqueue or run.
-        const result = await new Promise((resolve, reject) => {
-            const entry = {
-                req: { ...req },
-                enqueuedAt: (this.deps.now ?? Date.now)(),
-                newHash,
-                resolve,
-                reject,
-            };
-            const queue = this.queues.get(req.projectId) ?? [];
-            queue.push(entry);
+        // Hash was only an admission/cache optimization. The worker snapshots fresh
+        // bytes and hashes exactly those bytes when its queue slot actually starts.
+        return this.queueTask(req, (signal) => this.runOne(req, signal), (reason) => this.emitSkipped(req, reason));
+    }
+    getLanguage() { return this.deps.language?.() ?? 'en'; }
+    /** Stories share this manager's project/app concurrency, spend reservations
+     * and disposal. Only the task itself records its billable usage. */
+    scheduleTask(req, task) {
+        return this.queueTask(req, async (signal) => await task(signal) ? 'enqueued' : 'failed', () => { });
+    }
+    queueTask(req, run, skipped) {
+        if (this._disposed)
+            return Promise.resolve('skipped:not-found');
+        const queue = this.queues.get(req.projectId) ?? [];
+        // Bound retained request/context memory even when provider capacity stalls.
+        if (queue.length >= 200)
+            return Promise.resolve('failed');
+        return new Promise((resolve, reject) => {
+            queue.push({ req: { ...req }, enqueuedAt: (this.deps.now ?? Date.now)(), run, skipped, resolve, reject });
             this.queues.set(req.projectId, queue);
             this.pump(req.projectId);
         });
-        return result;
     }
     // Recorded month-to-date spend PLUS the optimistically-reserved spend of
     // generations already in flight for this project. Both budget gates read this
@@ -408,8 +502,7 @@ class FileSummaryManager {
             // TTL drop before starting. Distinct 'skipped:ttl' (not 'skipped:hash') so
             // the regenerate route can tell the user it was dropped, not silently 202.
             if (now - entry.enqueuedAt > this.queueTtlMs) {
-                this.emitSkipped(entry.req, 'ttl');
-                entry.resolve('skipped:ttl');
+                this.skipEntry(entry, 'ttl');
                 continue;
             }
             // Budget re-check at dequeue: an entry that crossed the monthly cap while
@@ -421,8 +514,7 @@ class FileSummaryManager {
                 const spend = this.effectiveSpend(entry.req.projectId);
                 const budget = this.deps.monthlyBudgetUsd();
                 if (spend >= budget) {
-                    this.emitSkipped(entry.req, 'budget');
-                    entry.resolve('skipped:budget');
+                    this.skipEntry(entry, 'budget');
                     continue;
                 }
             }
@@ -432,8 +524,7 @@ class FileSummaryManager {
             if (entry.req.jobId) {
                 const count = this.jobCounter.get(entry.req.jobId) ?? 0;
                 if (count >= this.perJobCap) {
-                    this.emitSkipped(entry.req, 'per-job-cap');
-                    entry.resolve('skipped:per-job-cap');
+                    this.skipEntry(entry, 'per-job-cap');
                     continue;
                 }
                 if (!this.jobCounter.has(entry.req.jobId) && this.jobCounter.size >= this.maxJobCounters) {
@@ -452,7 +543,8 @@ class FileSummaryManager {
             if (!entry.req.overrideBudget)
                 this.reserveSpend(projectId);
             const reservedSpend = !entry.req.overrideBudget;
-            const p = this.runOne(entry)
+            const p = this.runEntry(entry)
+                .then(entry.resolve)
                 .catch((err) => entry.reject(err))
                 .finally(() => {
                 if (reservedSpend)
@@ -479,22 +571,37 @@ class FileSummaryManager {
         for (const pid of [...this.queues.keys()])
             this.pump(pid);
     }
-    async runOne(entry) {
-        const { req } = entry;
+    skipEntry(entry, reason) {
+        try {
+            entry.skipped(reason);
+        }
+        catch { /* a closed WS transport cannot strand a request */ }
+        entry.resolve(`skipped:${reason}`);
+    }
+    async runEntry(entry) {
+        const controller = new AbortController();
+        this.activeControllers.add(controller);
+        try {
+            const result = await entry.run(controller.signal);
+            return controller.signal.aborted ? 'failed' : result;
+        }
+        finally {
+            this.activeControllers.delete(controller);
+        }
+    }
+    async runOne(req, signal) {
         const absolutePath = path.join(req.projectPath, req.relPath);
         const startedIso = new Date((this.deps.now ?? Date.now)()).toISOString();
         let contents;
         let fileHash;
         try {
-            contents = fs.readFileSync(absolutePath, 'utf8');
-            // Use the hash captured for THIS entry at enqueue time (never another
-            // entry's). Fall back to a recompute only if it was somehow not set.
-            fileHash = entry.newHash || (await computeFileHash(absolutePath));
+            const snapshot = readSourceSnapshot(req.projectPath, req.relPath);
+            contents = snapshot.toString('utf8');
+            fileHash = (0, crypto_1.createHash)('sha256').update(snapshot).digest('hex');
         }
         catch {
             this.emitSkipped(req, 'not-found');
-            entry.resolve('skipped:not-found');
-            return;
+            return 'skipped:not-found';
         }
         const tokens = Math.ceil(contents.length / TOKEN_CHARS_PER_TOKEN);
         let truncated = false;
@@ -506,20 +613,18 @@ class FileSummaryManager {
             promptContents = head + TRUNCATE_MARKER + tail;
         }
         const lang = (this.deps.language?.() ?? 'en');
-        const controller = new AbortController();
-        this.activeControllers.add(controller);
         try {
             const out = await this.deps.generate({
                 relPath: req.relPath,
+                repositoryId: req.repositoryId,
                 contents: promptContents,
                 truncated,
                 language: lang,
-            }, controller.signal);
+            }, signal);
             // The project may have been removed (and its DB closed) while the provider
             // ran. Skip all DB/disk/broadcast work so we never touch a closed handle.
             if (this._disposed) {
-                entry.resolve('failed');
-                return;
+                return 'failed';
             }
             // Cap a runaway LLM summary at the schema bound so writeSummary's
             // validation never rejects a real generation (it would otherwise throw and
@@ -532,7 +637,7 @@ class FileSummaryManager {
                 summary: boundedSummary,
                 language: lang,
                 generatedAt: new Date((this.deps.now ?? Date.now)()).toISOString(),
-                generatedBy: { model: out.model, promptVersion: CURRENT_PROMPT_VERSION, truncated },
+                generatedBy: { model: out.model, promptVersion: exports.CURRENT_PROMPT_VERSION, truncated },
                 triggeredBy: req.triggeredBy,
             };
             // Relocate-artifacts: summaries OUTPUT to the workspace when relocated
@@ -541,7 +646,7 @@ class FileSummaryManager {
             const summaryRoot = req.summaryRoot ?? req.projectPath;
             writeSummary(summaryRoot, req.relPath, payload, summaryRoot === req.projectPath);
             // Keep the watcher's negative-cache a correct superset.
-            this.knownSummaries.get(req.projectId)?.add(req.relPath);
+            this.knownSummaries.get(repositoryKey(req.projectId, req.repositoryId))?.add(req.relPath);
             try {
                 (0, ai_invocations_1.recordInvocation)(this.deps.db, {
                     id: (0, crypto_1.randomUUID)(),
@@ -570,15 +675,23 @@ class FileSummaryManager {
                 // spending under-counts with no trace.
                 console.error('[file-summary] recordInvocation (success) failed:', err);
             }
-            this.deps.broadcast(buildSummaryUpdated(req.projectId, payload, false));
+            let stale = isSummaryMetadataStale(payload, this.getLanguage());
+            try {
+                stale ||= await computeFileHash(absolutePath) !== fileHash;
+            }
+            catch {
+                stale = true;
+            }
+            if (this._disposed || signal.aborted)
+                return 'failed';
+            this.deps.broadcast(buildSummaryUpdated(req.projectId, payload, stale, req.repositoryId));
             this.deps.broadcast({ type: 'spending.invalidated', projectId: req.projectId });
-            entry.resolve('enqueued');
+            return 'enqueued';
         }
         catch (err) {
             // Disposed mid-flight (project removed) — DB is closed; skip all writes.
             if (this._disposed) {
-                entry.resolve('failed');
-                return;
+                return 'failed';
             }
             const reason = err instanceof Error ? err.message : String(err);
             // A timeout/abort kills the child AFTER the provider may have billed tokens.
@@ -616,25 +729,23 @@ class FileSummaryManager {
             const failedMsg = {
                 type: 'file.summary_failed',
                 projectId: req.projectId,
+                ...(req.repositoryId ? { repositoryId: req.repositoryId } : {}),
                 path: req.relPath,
                 reason,
             };
             this.deps.broadcast(failedMsg);
             // Resolve with 'failed' (not 'enqueued') so a caller awaiting enqueue()
             // can distinguish a failed generation from a successful one.
-            entry.resolve('failed');
-        }
-        finally {
-            this.activeControllers.delete(controller);
+            return 'failed';
         }
     }
     /** `summaryRoot` (relocate-artifacts) is where the summary JSON lives — the
      *  workspace when relocated, else === projectPath. */
-    markStale(projectPath, projectId, relPath, summaryRoot) {
+    markStale(projectPath, projectId, relPath, summaryRoot, repositoryId) {
         const existing = readSummary(summaryRoot ?? projectPath, relPath);
         if (!existing)
             return;
-        this.deps.broadcast(buildSummaryUpdated(projectId, existing, true));
+        this.deps.broadcast(buildSummaryUpdated(projectId, existing, true, repositoryId));
     }
     /**
      * Watch the repo SOURCE tree (`projectPath`) for edits and mark the
@@ -642,28 +753,87 @@ class FileSummaryManager {
      * summary JSON lives (workspace when relocated) — source is watched at
      * `projectPath`, summaries are scanned/swept/marked at `summaryRoot`. When
      * omitted `summaryRoot` defaults to `projectPath` (legacy, byte-identical).
+     *
+     * Never throws and never lets the watcher take the process down: a watcher
+     * that cannot start (or later dies of fd/inotify exhaustion) leaves the
+     * project attached in `degraded` status, so later Code-Explorer requests do
+     * not retry a doomed recursive watch on every hit.
      */
-    attachWatcher(projectId, projectPath, summaryRoot) {
-        if (this.watchers.has(projectId))
+    attachWatcher(projectId, projectPath, summaryRoot, repositoryId) {
+        if (this._disposed)
             return;
+        const key = repositoryKey(projectId, repositoryId);
+        const previous = this.watchers.get(key);
+        if (previous) {
+            // ReadDirectoryChangesW dies with EPERM when its root is removed. An
+            // explicit explorer request may reattach after it reappears, with a
+            // cooldown and a hard limit; resource exhaustion never retries here.
+            if (previous.status !== 'degraded' || previous.retryAfter === undefined ||
+                Date.now() < previous.retryAfter || (previous.restarts ?? 0) >= 3)
+                return;
+            try {
+                if (!fs.statSync(projectPath).isDirectory())
+                    return;
+            }
+            catch {
+                return;
+            }
+            this.closeWatcherState(previous);
+        }
         const sumRoot = summaryRoot ?? projectPath;
-        this.knownSummaries.set(projectId, this.scanKnownSummaries(sumRoot));
+        this.knownSummaries.set(key, this.scanKnownSummaries(sumRoot));
         // Reclaim summary JSON files whose source file was renamed/deleted since the
         // last session. Runs once per project per session (attachWatcher is
-        // idempotent) and is capped at 200/pass inside sweepOrphans. The chokidar
-        // watcher only sees 'change', never 'unlink', so this is the only reaper.
+        // idempotent) and is capped at 200/pass inside sweepOrphans. The watcher
+        // only marks stale, never deletes, so this is the only reaper.
         // sweepOrphans resolves source files against the repo, so it must know both:
         // summaries under sumRoot, source under projectPath.
         try {
             sweepOrphans(sumRoot, undefined, projectPath);
         }
         catch { /* best effort */ }
-        // CRITICAL: prune build/dep trees (node_modules, dist, target, src-tauri/target,
-        // dot-dirs, …) from the recursive watch. Watching a Rust/Tauri `target/` tree
-        // opened ~10k file descriptors and broke terminal spawning under fd pressure.
-        // The predicate is tested against each path relative to the project root so a
-        // dot-segment in the absolute prefix (the user's home dir) can't false-positive.
+        // Registered BEFORE the watch is created so a failed start still counts as
+        // attached (degraded) — idempotency is what stops a retry storm.
+        const state = { projectPath, status: 'degraded', close: () => { }, timers: new Map(), restarts: previous ? (previous.restarts ?? 0) + 1 : 0 };
+        this.watchers.set(key, state);
+        const engine = this.deps.watchEngine ?? resolveWatchEngine();
+        const onChange = (raw) => this.onSourceChanged(projectId, state, raw, sumRoot, repositoryId);
+        const onError = (err) => this.onWatcherError(projectId, state, err);
+        try {
+            state.close = engine === 'native'
+                ? this.startNativeWatcher(projectPath, onChange, onError)
+                : this.startChokidarWatcher(projectPath, onChange, onError);
+            state.status = engine;
+        }
+        catch (err) {
+            this.degradeWatcher(projectId, state, err, 'start');
+        }
+    }
+    /** Current watcher status for a project, or null when never attached. */
+    watcherStatus(projectId, repositoryId) {
+        return this.watchers.get(repositoryKey(projectId, repositoryId))?.status ?? null;
+    }
+    /** One kernel-level recursive watch for the whole tree (FSEvents on macOS,
+     *  ReadDirectoryChangesW on Windows). `filename` arrives relative to the
+     *  watched root. `persistent: false` — the HTTP server keeps the process
+     *  alive; a watcher never should. */
+    startNativeWatcher(projectPath, onChange, onError) {
+        const watch = this.deps.fsWatch ?? fs.watch;
+        const watcher = watch(projectPath, { recursive: true, persistent: false }, (_event, filename) => onChange(filename));
+        watcher.on('error', onError);
+        return () => { try {
+            watcher.close();
+        }
+        catch { /* best effort */ } };
+    }
+    /** chokidar (Linux): one inotify watch per file/dir, so the build/dep trees
+     *  MUST be pruned — a Rust `target/` or `node_modules` alone is tens of
+     *  thousands of watches. The predicate is tested against each path relative
+     *  to the project root so a dot-segment in the absolute prefix (the user's
+     *  home dir) can't false-positive. */
+    startChokidarWatcher(projectPath, onChange, onError) {
         const watcher = chokidar_1.default.watch(projectPath, {
+            followSymlinks: false,
             ignored: (p) => {
                 const rel = path.relative(projectPath, p);
                 if (!rel || rel.startsWith('..'))
@@ -671,25 +841,105 @@ class FileSummaryManager {
                 return (0, build_dirs_1.isInBuildDir)(rel);
             },
             ignoreInitial: true,
-            persistent: true,
-            // Coalesce partial-write churn so one logical edit fires one event.
-            awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 100 },
-        });
-        watcher.on('change', (changed) => {
-            // The summary store keys off POSIX forward-slash relpaths everywhere
-            // (the REST normalizeRel, pathHash, knownSummaries seeding). On Windows
-            // path.relative yields backslashes, so normalize before lookup/markStale —
-            // otherwise `known.has(rel)` always misses and edits never mark stale.
-            const rel = path.relative(projectPath, changed).split(path.sep).join('/');
-            if (!rel || rel.startsWith('..'))
-                return;
-            // Skip the readSummary disk hit when this file provably has no summary.
-            const known = this.knownSummaries.get(projectId);
-            if (known && !known.has(rel))
-                return;
-            this.markStale(projectPath, projectId, rel, sumRoot);
+            // A dir we cannot read is not a reason to lose the whole watcher.
+            ignorePermissionErrors: true,
+            persistent: false,
         });
-        this.watchers.set(projectId, { projectPath, watcher });
+        watcher.on('change', (changed) => onChange(changed));
+        watcher.on('unlink', (removed) => onChange(removed));
+        watcher.on('error', onError);
+        return () => { void watcher.close().catch(() => { }); };
+    }
+    /** Shared change funnel for both engines: normalise to a POSIX relpath, drop
+     *  build/dep/dot trees and files that provably have no summary, then debounce
+     *  per path before the (hash-checked) stale mark. */
+    onSourceChanged(projectId, state, raw, sumRoot, repositoryId) {
+        if (raw == null || this._disposed || state.status === 'degraded')
+            return;
+        const name = typeof raw === 'string' ? raw : raw.toString();
+        // Native engines report paths relative to the watched root (Windows with
+        // backslashes); chokidar reports absolute paths. Meet in the middle.
+        const relRaw = path.isAbsolute(name) ? path.relative(state.projectPath, name) : name;
+        // The summary store keys off POSIX forward-slash relpaths everywhere (the
+        // REST normalizeRel, pathHash, knownSummaries seeding) — normalise before
+        // lookup/markStale, otherwise `known.has(rel)` always misses on Windows.
+        const rel = relRaw.split(path.sep).join('/');
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+            return;
+        if ((0, build_dirs_1.isInBuildDir)(rel))
+            return;
+        // Skip the disk hits when this file provably has no summary.
+        const known = this.knownSummaries.get(repositoryKey(projectId, repositoryId));
+        if (known && !known.has(rel))
+            return;
+        const pending = state.timers.get(rel);
+        if (pending)
+            clearTimeout(pending);
+        const timer = setTimeout(() => {
+            state.timers.delete(rel);
+            void this.markStaleIfChanged(state.projectPath, projectId, rel, sumRoot, repositoryId);
+        }, exports.WATCH_DEBOUNCE_MS);
+        timer.unref?.();
+        state.timers.set(rel, timer);
+    }
+    /** Watcher-side markStale: broadcast ONLY when the source really differs from
+     *  what the summary was generated against. A save that leaves the bytes
+     *  unchanged, an editor's temp-file dance, or a replayed/coalesced kernel
+     *  event must not flag a still-valid summary. A source that vanished IS
+     *  stale — the summary describes a file that is gone. */
+    async markStaleIfChanged(projectPath, projectId, rel, sumRoot, repositoryId) {
+        const existing = readSummary(sumRoot, rel);
+        if (!existing)
+            return;
+        let hash = null;
+        try {
+            hash = await computeFileHash(path.join(projectPath, rel));
+        }
+        catch {
+            hash = null;
+        }
+        if (hash !== null && hash === existing.fileHash)
+            return;
+        if (this._disposed)
+            return;
+        this.deps.broadcast(buildSummaryUpdated(projectId, existing, true, repositoryId));
+    }
+    onWatcherError(projectId, state, err) {
+        const code = errnoCode(err);
+        if (state.status === 'native' && (code === 'EPERM' || code === 'EACCES')) {
+            state.retryAfter = Date.now() + 30_000;
+            this.degradeWatcher(projectId, state, err, 'runtime');
+            return;
+        }
+        if (code && !WATCHER_EXHAUSTION_CODES.has(code) && state.status !== 'degraded') {
+            // Transient and local (a dir vanished mid-scan, a permission hiccup on
+            // one subtree): keep watching, just log.
+            console.warn('[file-summary] watcher error', JSON.stringify({ projectId, code, error: errMessage(err) }));
+            return;
+        }
+        this.degradeWatcher(projectId, state, err, 'runtime');
+    }
+    /** Release the watcher (and, with it, every fd/watch it holds) and park the
+     *  project in degraded mode. Logged once; only a terminated native root
+     *  watcher may be reattached by a later explicit request after cooldown. */
+    degradeWatcher(projectId, state, err, phase) {
+        const alreadyDegraded = state.status === 'degraded' && phase === 'runtime';
+        state.status = 'degraded';
+        this.closeWatcherState(state);
+        if (alreadyDegraded)
+            return;
+        console.warn('[file-summary] watcher degraded — edits will not mark summaries stale until the next explicit read/regenerate', JSON.stringify({ projectId, projectPath: state.projectPath, phase, code: errnoCode(err) ?? null, error: errMessage(err) }));
+    }
+    closeWatcherState(state) {
+        const close = state.close;
+        state.close = () => { };
+        try {
+            close();
+        }
+        catch { /* best effort */ }
+        for (const timer of state.timers.values())
+            clearTimeout(timer);
+        state.timers.clear();
     }
     /** Read the relPaths of every summary on disk into a set (one-time at attach). */
     scanKnownSummaries(projectPath) {
@@ -714,13 +964,14 @@ class FileSummaryManager {
         }
         return set;
     }
-    detachWatcher(projectId) {
-        const state = this.watchers.get(projectId);
+    detachWatcher(projectId, repositoryId) {
+        const key = repositoryKey(projectId, repositoryId);
+        const state = this.watchers.get(key);
         if (!state)
             return;
-        void state.watcher.close();
-        this.watchers.delete(projectId);
-        this.knownSummaries.delete(projectId);
+        this.closeWatcherState(state);
+        this.watchers.delete(key);
+        this.knownSummaries.delete(key);
     }
     /** Full teardown for a single manager: stop accepting work, abort any in-flight
      *  provider child (so it is not orphaned past project removal), reject queued
@@ -743,34 +994,30 @@ class FileSummaryManager {
         // Reject still-queued entries so awaiting callers settle (skipped, not hung).
         for (const [, queue] of this.queues) {
             for (const entry of queue) {
-                try {
-                    this.emitSkipped(entry.req, 'not-found');
-                    entry.resolve('skipped:not-found');
-                }
-                catch { /* best effort */ }
+                this.skipEntry(entry, 'not-found');
             }
         }
         this.queues.clear();
         this.inFlightByKey.clear();
         this.pendingSpend.clear();
-        for (const [, state] of this.watchers) {
-            try {
-                void state.watcher.close();
-            }
-            catch { /* best effort */ }
-        }
+        for (const [, state] of this.watchers)
+            this.closeWatcherState(state);
         this.watchers.clear();
         this.knownSummaries.clear();
     }
-    /** Close every watcher. Called on graceful server shutdown so chokidar's
-     *  underlying fsevents/inotify handles are released, never leaked. */
+    /** Close every watcher. Called on graceful server shutdown so the
+     *  underlying FSEvents/ReadDirectoryChangesW/inotify handles are released,
+     *  never leaked. */
     disposeAll() {
         this.dispose();
     }
     async flush() {
         // Drain until no pending work remains.
         while (this.pending.size > 0 || this.hasQueued()) {
-            await Promise.allSettled(Array.from(this.pending));
+            if (this.pending.size > 0)
+                await Promise.allSettled(Array.from(this.pending));
+            else
+                await new Promise(resolve => setTimeout(resolve, 0)); // let another manager release the shared slot
         }
     }
     hasQueued() {
@@ -783,6 +1030,7 @@ class FileSummaryManager {
         const msg = {
             type: 'file.summary_skipped',
             projectId: req.projectId,
+            ...(req.repositoryId ? { repositoryId: req.repositoryId } : {}),
             path: req.relPath,
             reason,
         };
@@ -790,10 +1038,11 @@ class FileSummaryManager {
     }
 }
 exports.FileSummaryManager = FileSummaryManager;
-function buildSummaryUpdated(projectId, payload, stale) {
+function buildSummaryUpdated(projectId, payload, stale, repositoryId) {
     const msg = {
         type: 'file.summary_updated',
         projectId,
+        ...(repositoryId ? { repositoryId } : {}),
         path: payload.path,
         summaryAvailable: true,
         stale,