@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/word-index.js

@@ -20,6 +20,7 @@ import { isAtOrAboveHomeDir, normalizeEphemeralMapKey } from "./path-utils.js";
 import { createDebounceScheduler, } from "./persist-debounce.js";
 import { getWordIndexMaxFilesDerived } from "./project-scale.js";
 import { logWordIndex } from "./word-index-logger.js";
+import { createDeadline, forEachCooperatively, yieldIfOverBudget, } from "./cooperative-budget.js";
 /**
  * The single normalizer every word-index path key folds through (#1025). The
  * CHEAP form — slash-fold + win32-lowercase, NO filesystem I/O — because the
@@ -94,52 +95,112 @@ export function tokenizeLine(line) {
     }
     return tokens;
 }
+const WORD_INDEX_BUILD_YIELD_BUDGET_MS = 8;
 /**
- * Build the inverted index from file contents. One posting per (token, file,
- * line) — a token repeated on the same line counts once — so term frequency is
- * "lines mentioning the token", a stable signal that doesn't over-weight a line
- * that repeats an identifier. Document length is the total indexed token count.
+ * A line at or above this length is treated as a yield checkpoint on its own.
+ * The per-50-lines cadence is a proxy for work that only holds on hand-written
+ * source: a minified/bundled single-line file up to {@link WORD_INDEX_MAX_BYTES}
+ * that the source filter did not exclude would otherwise get ZERO in-document
+ * yields — one unbroken tokenize+push burst far above the budget (#1197 review
+ * finding 4). Checking the clock after any long line makes the cooperativeness
+ * claim true per BYTE, not just per line count.
  */
+const WORD_INDEX_LONG_LINE_YIELD_CHARS = 4096;
+/**
+ * Shared cooperative time-slicer for every bulk word-index path (#1197).
+ *
+ * Time-based, not count-based: "yield every N items" is only a bound when the
+ * per-item cost is bounded too, and the incremental refresh's per-document cost
+ * grows with the corpus (each replacement filters shared posting arrays). The
+ * #1197 outage was exactly that shape — 239 stale documents held pi's event loop
+ * for seconds between two "every 100 files" checkpoints. Callers combine this
+ * The shared deadline is checked at every bounded work unit so abort latency
+ * and occupancy are governed by the same monotonic budget.
+ */
+function createEmptyWordIndex(truncated) {
+    return {
+        postings: new Map(),
+        docLengths: new PathKeyedMap(wordIndexKey),
+        totalTokens: 0,
+        docCount: 0,
+        truncated,
+        forward: new PathKeyedMap(wordIndexKey),
+        fileMtimes: new PathKeyedMap(wordIndexKey),
+        fileSizes: new PathKeyedMap(wordIndexKey),
+    };
+}
+function indexWordLine(index, filePath, line, lineNumber, tokenLineCounts) {
+    const lineTokens = tokenizeLine(line);
+    const seenOnLine = new Set();
+    for (const token of lineTokens) {
+        if (seenOnLine.has(token))
+            continue;
+        seenOnLine.add(token);
+        const arr = index.postings.get(token);
+        if (arr)
+            arr.push({ file: filePath, line: lineNumber });
+        else
+            index.postings.set(token, [{ file: filePath, line: lineNumber }]);
+        tokenLineCounts.set(token, (tokenLineCounts.get(token) ?? 0) + 1);
+    }
+    return lineTokens.length;
+}
+function finishWordIndexDocument(index, doc, docLength, tokenLineCounts) {
+    index.docLengths.set(doc.path, docLength);
+    index.forward?.set(doc.path, tokenLineCounts);
+    index.fileMtimes.set(doc.path, doc.mtimeMs ?? 0);
+    index.fileSizes.set(doc.path, doc.size ?? Buffer.byteLength(doc.content, "utf-8"));
+    index.totalTokens += docLength;
+    index.docCount += 1;
+}
+function indexWordDocument(index, doc) {
+    const lines = doc.content.split(/\r?\n/);
+    const tokenLineCounts = new Map();
+    let docLength = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        docLength += indexWordLine(index, doc.path, lines[i], i + 1, tokenLineCounts);
+    }
+    finishWordIndexDocument(index, doc, docLength, tokenLineCounts);
+}
 export function buildWordIndex(files) {
-    const postings = new Map();
-    const docLengths = new PathKeyedMap(wordIndexKey);
-    const forward = new PathKeyedMap(wordIndexKey);
-    const fileMtimes = new PathKeyedMap(wordIndexKey);
-    let totalTokens = 0;
-    for (const { path: filePath, content, mtimeMs } of files) {
-        const lines = content.split(/\r?\n/);
-        let docLength = 0;
+    const index = createEmptyWordIndex(files.truncated ?? false);
+    for (const doc of files)
+        indexWordDocument(index, doc);
+    return index;
+}
+/**
+ * Cooperative production builder for bulk/cold paths. It produces the exact
+ * same index as {@link buildWordIndex}, but time-slices both between documents
+ * and within a large document so startup warmup cannot monopolize pi's TUI
+ * event loop (#1197). The index is private until this resolves, so a superseded
+ * build never publishes a partial replacement.
+ */
+export async function buildWordIndexAsync(files, shouldContinue = () => true) {
+    const index = createEmptyWordIndex(files.truncated ?? false);
+    const deadline = createDeadline(WORD_INDEX_BUILD_YIELD_BUDGET_MS);
+    for (const doc of files) {
+        if (!shouldContinue())
+            throw new Error("word index build superseded");
+        const lines = doc.content.split(/\r?\n/);
         const tokenLineCounts = new Map();
+        let docLength = 0;
         for (let i = 0; i < lines.length; i += 1) {
-            const lineTokens = tokenizeLine(lines[i]);
-            docLength += lineTokens.length;
-            const seenOnLine = new Set();
-            for (const token of lineTokens) {
-                if (seenOnLine.has(token))
-                    continue;
-                seenOnLine.add(token);
-                const arr = postings.get(token);
-                if (arr)
-                    arr.push({ file: filePath, line: i + 1 });
-                else
-                    postings.set(token, [{ file: filePath, line: i + 1 }]);
-                tokenLineCounts.set(token, (tokenLineCounts.get(token) ?? 0) + 1);
+            const line = lines[i];
+            docLength += indexWordLine(index, doc.path, line, i + 1, tokenLineCounts);
+            if (line.length >= WORD_INDEX_LONG_LINE_YIELD_CHARS ||
+                deadline.expired()) {
+                await yieldIfOverBudget(deadline);
+                if (!shouldContinue())
+                    throw new Error("word index build superseded");
             }
         }
-        docLengths.set(filePath, docLength);
-        forward.set(filePath, tokenLineCounts);
-        fileMtimes.set(filePath, mtimeMs ?? 0);
-        totalTokens += docLength;
+        finishWordIndexDocument(index, doc, docLength, tokenLineCounts);
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
+            if (!shouldContinue())
+                throw new Error("word index build superseded");
+        }
     }
-    return {
-        postings,
-        docLengths,
-        totalTokens,
-        docCount: files.length,
-        truncated: files.truncated ?? false,
-        forward,
-        fileMtimes,
-    };
+    return index;
 }
 /**
  * Remove `filePath`'s postings/docLength/forward entry from `index` in place,
@@ -175,6 +236,7 @@ export function removeWordIndexDocument(index, filePath) {
     index.docLengths.delete(filePath);
     index.forward.delete(filePath);
     index.fileMtimes.delete(filePath);
+    index.fileSizes.delete(filePath);
     index.totalTokens -= docLength;
     index.docCount = Math.max(0, index.docCount - 1);
     return true;
@@ -238,6 +300,117 @@ export function updateWordIndexDocument(index, doc) {
     // legal on-disk mtime (SOURCE_DATE_EPOCH=0, archive extraction) and would
     // collide, leaving such a file never re-tokenized (#958 review F2).
     index.fileMtimes.set(doc.path, -1);
+    // Size is likewise recorded for the #1105 mtime+size refresh gate. The -1
+    // mtime already forces a re-read next session, so this value only keeps the
+    // map dense (parallel to fileMtimes); store the real byte length so a
+    // deserialize→reserialize round-trip before any refresh carries a truthful
+    // size rather than a placeholder.
+    index.fileSizes.set(doc.path, Buffer.byteLength(doc.content, "utf-8"));
+    index.totalTokens += docLength;
+    index.docCount += 1;
+    return true;
+}
+async function stageWordIndexDocumentRemoval(index, filePath, shouldContinue) {
+    if (!index.forward)
+        return undefined;
+    const tokenLineCounts = index.forward.get(filePath);
+    if (!tokenLineCounts)
+        return undefined;
+    const removedKey = wordIndexKey(filePath);
+    const postings = new Map();
+    const deadline = createDeadline(WORD_INDEX_BUILD_YIELD_BUDGET_MS);
+    for (const token of tokenLineCounts.keys()) {
+        if (!shouldContinue())
+            throw new Error("word index refresh superseded");
+        const arr = index.postings.get(token);
+        if (!arr)
+            continue;
+        const next = [];
+        for (const hit of arr) {
+            if (wordIndexKey(hit.file) !== removedKey)
+                next.push(hit);
+            if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
+                if (!shouldContinue())
+                    throw new Error("word index refresh superseded");
+            }
+        }
+        postings.set(token, next.length > 0 ? next : undefined);
+    }
+    return { postings, docLength: index.docLengths.get(filePath) ?? 0 };
+}
+function commitWordIndexDocumentRemoval(index, filePath, staged) {
+    for (const [token, hits] of staged.postings) {
+        if (hits)
+            index.postings.set(token, hits);
+        else
+            index.postings.delete(token);
+    }
+    index.docLengths.delete(filePath);
+    index.forward?.delete(filePath);
+    index.fileMtimes.delete(filePath);
+    index.fileSizes.delete(filePath);
+    index.totalTokens -= staged.docLength;
+    index.docCount = Math.max(0, index.docCount - 1);
+}
+/** Cooperative, atomically-published removal used only by bulk refresh. */
+export async function removeWordIndexDocumentAsync(index, filePath, shouldContinue = () => true) {
+    const staged = await stageWordIndexDocumentRemoval(index, filePath, shouldContinue);
+    if (!staged)
+        return false;
+    if (!shouldContinue())
+        throw new Error("word index refresh superseded");
+    commitWordIndexDocumentRemoval(index, filePath, staged);
+    return true;
+}
+/** Cooperative replacement whose old/new state is committed without an await. */
+export async function updateWordIndexDocumentAsync(index, doc, shouldContinue = () => true) {
+    if (!index.forward)
+        return false;
+    const removal = index.forward.has(doc.path)
+        ? await stageWordIndexDocumentRemoval(index, doc.path, shouldContinue)
+        : undefined;
+    if (index.forward.has(doc.path) && !removal)
+        return false;
+    const perTokenHits = new Map();
+    let docLength = 0;
+    const lines = doc.content.split(/\r?\n/);
+    await forEachCooperatively(lines, (line, i) => {
+        const lineTokens = tokenizeLine(line);
+        docLength += lineTokens.length;
+        const seenOnLine = new Set();
+        for (const token of lineTokens) {
+            if (seenOnLine.has(token))
+                continue;
+            seenOnLine.add(token);
+            const arr = perTokenHits.get(token);
+            if (arr)
+                arr.push(i + 1);
+            else
+                perTokenHits.set(token, [i + 1]);
+        }
+    }, {
+        budgetMs: WORD_INDEX_BUILD_YIELD_BUDGET_MS,
+        shouldContinue,
+        abortMessage: "word index refresh superseded",
+    });
+    if (!shouldContinue())
+        throw new Error("word index refresh superseded");
+    if (removal)
+        commitWordIndexDocumentRemoval(index, doc.path, removal);
+    const tokenLineCounts = new Map();
+    for (const [token, lineNumbers] of perTokenHits) {
+        tokenLineCounts.set(token, lineNumbers.length);
+        const hits = lineNumbers.map((line) => ({ file: doc.path, line }));
+        const arr = index.postings.get(token);
+        if (arr)
+            arr.push(...hits);
+        else
+            index.postings.set(token, hits);
+    }
+    index.docLengths.set(doc.path, docLength);
+    index.forward.set(doc.path, tokenLineCounts);
+    index.fileMtimes.set(doc.path, -1);
+    index.fileSizes.set(doc.path, Buffer.byteLength(doc.content, "utf-8"));
     index.totalTokens += docLength;
     index.docCount += 1;
     return true;
@@ -262,7 +435,7 @@ export const WORD_INDEX_MAX_BYTES = 512 * 1024;
  * `shouldContinue` lets a session-scoped caller abort early (session
  * superseded) without this module knowing about RuntimeCoordinator.
  */
-export async function collectWordIndexDocs(root, shouldContinue = () => true) {
+export async function collectWordIndexDocs(root, shouldContinue = () => true, preflightFiles) {
     const { collectSourceFilesAsync } = await import("./source-filter.js");
     // #747 hardening: pass the cap INTO the walk — without it,
     // `collectSourceFilesAsync` defaults to an unbounded traversal and the
@@ -272,29 +445,39 @@ export async function collectWordIndexDocs(root, shouldContinue = () => true) {
     // visited-entry budget (DEFAULT_MAX_SCAN_ENTRIES), so a mixed tree with few
     // source files among a huge pile of non-source files can't force a
     // full-tree walk either; an index over the truncated list is acceptable.
-    const maxFiles = getWordIndexMaxFilesDerived(root);
+    const maxFiles = preflightFiles?.length ?? getWordIndexMaxFilesDerived(root);
     // #894 review: prioritize code kinds within the cap — with broadened
     // enumeration, thousands of data/doc files (locale JSON, fixtures, …)
     // ahead of the code dirs in walk order could exhaust `maxFiles` and evict
     // real source files from the index entirely (DOC_FILE_PENALTY can't
     // rescue a file that never made the slice).
-    const files = await collectSourceFilesAsync(root, {
-        maxFiles,
-        prioritizeCodeKinds: true,
-    });
-    const truncated = files.length === maxFiles;
+    const files = preflightFiles
+        ? preflightFiles.map((file) => file.path)
+        : await collectSourceFilesAsync(root, {
+            maxFiles,
+            prioritizeCodeKinds: true,
+        });
+    const truncated = preflightFiles?.truncated ?? files.length === maxFiles;
     const docs = Object.assign([], { truncated, skipped: 0 });
     if (!shouldContinue())
         return docs;
-    let processed = 0;
+    const deadline = createDeadline(WORD_INDEX_BUILD_YIELD_BUDGET_MS);
     for (const file of files.slice(0, maxFiles)) {
+        if (!shouldContinue())
+            return docs;
         try {
+            // A preflight list saves the second full WALK, but its metadata may be
+            // stale by the time this rebuild reads the file. Re-stat each document at
+            // content-read time so the stored freshness stamp describes the bytes we
+            // actually index and the next incremental refresh cannot miss a change in
+            // the walk-to-read window (#1302).
             const stat = fs.statSync(file);
             if (stat.size <= WORD_INDEX_MAX_BYTES) {
                 docs.push({
                     path: file,
                     content: fs.readFileSync(file, "utf-8"),
                     mtimeMs: stat.mtimeMs,
+                    size: stat.size,
                 });
             }
             else {
@@ -308,8 +491,7 @@ export async function collectWordIndexDocs(root, shouldContinue = () => true) {
             // unreadable / vanished file — skip, but count it (see above).
             docs.skipped += 1;
         }
-        if (++processed % 100 === 0) {
-            await new Promise((resolve) => setImmediate(resolve));
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
             if (!shouldContinue())
                 return docs;
         }
@@ -317,14 +499,44 @@ export async function collectWordIndexDocs(root, shouldContinue = () => true) {
     return docs;
 }
 const WORD_INDEX_INCREMENTAL_CHURN_THRESHOLD = 0.3;
+// A ratio alone misclassifies one stale file in a three-file project as dense.
+// Below this absolute floor, per-document replacement is bounded and cheaper
+// than a second full walk/read even when the percentage is high (#1197).
+const WORD_INDEX_DENSE_REFRESH_MIN_DOCUMENTS = 32;
+/**
+ * Cost of one file's stat+read+decode expressed in tokenizer-token units, so
+ * the work model below can compare a path that re-reads EVERY file (full
+ * rebuild) against one that re-reads only the stale files (incremental) in a
+ * single currency. One read ≈ 300 tokens at the ~1 µs/token measured below.
+ * Order-of-magnitude by design — it only has to keep a tiny-vocabulary corpus
+ * (where posting scans are nearly free) from being sent to a full rebuild that
+ * re-reads everything to save a handful of array filters.
+ */
+const WORD_INDEX_FILE_READ_TOKEN_COST = 300;
+/**
+ * Cost of scanning ONE posting-array element (the `wordIndexKey` compare in
+ * {@link removeWordIndexDocument}'s filter) relative to tokenizing one token,
+ * so both sides of the model below are denominated in tokens. Measured on this
+ * repository's own 2,062-document corpus: 213 ns per element scan against 979 ns
+ * per token — and the resulting predicted crossover (23 stale documents) lands
+ * on the directly measured one (~21, from 97.8 ms per document replacement
+ * against a 1,436 ms rebuild + re-read). The synthetic high-df corpus in the
+ * #1197 probe gives 0.09, so this is the conservative (incremental-favouring)
+ * end of the observed range.
+ */
+const WORD_INDEX_POSTING_SCAN_TOKEN_COST = 0.2;
 /**
  * Refresh a serializer-v2 index from the current bounded source-file set.
- * The walk/stat pass is cheap; only stale/new documents are read and tokenized.
- * Throws when the index cannot be updated safely so callers can full-rebuild.
+ * The walk/stat pass is cheap; only sparse stale/new documents are read and
+ * tokenized. Expected dense/legacy states return `full-required` BEFORE any
+ * mutation; unexpected corruption or supersession still throws.
  */
 export async function refreshWordIndexIncrementally(index, root, shouldContinue = () => true) {
-    if (!index.forward || !index.fileMtimes) {
-        throw new Error("word index lacks incremental metadata");
+    if (!index.forward || !index.fileMtimes || !index.fileSizes) {
+        return {
+            mode: "full-required",
+            reason: "missing-incremental-metadata",
+        };
     }
     const { collectSourceFilesAsync } = await import("./source-filter.js");
     const maxFiles = getWordIndexMaxFilesDerived(root);
@@ -347,17 +559,33 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
     // `wordIndexKey` keeps build/edit/refresh convergent; `current`'s value
     // retains the raw walk path for the stat/read and for the display key.
     const current = new Map();
+    // Check both supersession and the monotonic budget at every stat unit. Unlike
+    // the former modulus cadence, this remains bounded as per-file work changes.
+    const deadline = createDeadline(WORD_INDEX_BUILD_YIELD_BUDGET_MS);
     for (const file of walked) {
+        if (!shouldContinue())
+            throw new Error("word index refresh superseded");
         try {
             const stat = fs.statSync(file);
             if (stat.size <= WORD_INDEX_MAX_BYTES) {
-                current.set(wordIndexKey(file), { path: file, mtimeMs: stat.mtimeMs });
+                current.set(wordIndexKey(file), {
+                    path: file,
+                    mtimeMs: stat.mtimeMs,
+                    size: stat.size,
+                });
             }
         }
         catch {
             // A file vanishing between walk and stat is simply absent.
         }
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
+            if (!shouldContinue())
+                throw new Error("word index refresh superseded");
+        }
     }
+    const preflightFiles = Object.assign([...current.values()], {
+        truncated: walked.length === maxFiles,
+    });
     const oldSet = new Set([...index.docLengths.keys()].map(wordIndexKey));
     let changedSet = 0;
     for (const key of oldSet)
@@ -368,14 +596,85 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
             changedSet++;
     const denominator = Math.max(oldSet.size, current.size, 1);
     if (changedSet / denominator > WORD_INDEX_INCREMENTAL_CHURN_THRESHOLD) {
-        throw new Error("word index file-set churn exceeds incremental threshold");
+        return { mode: "full-required", reason: "file-set-churn", preflightFiles };
+    }
+    // Replacing one document filters every shared posting array for that
+    // document's tokens. That is excellent for a sparse edit, but repeating it
+    // for most of the corpus becomes effectively quadratic. Decide the dense
+    // transition BEFORE dropping or editing anything so the old index remains a
+    // valid fallback until a separately-built full replacement is ready (#1197).
+    let staleDocuments = 0;
+    for (const { path: file, mtimeMs, size } of current.values()) {
+        if (index.fileMtimes.get(file) !== mtimeMs ||
+            (index.fileSizes.get(file) ?? -1) !== size) {
+            staleDocuments += 1;
+        }
+    }
+    // Density alone is NOT a bound (#1197 review finding 1): the per-document cost
+    // GROWS with the corpus, so a stale set comfortably under any fixed ratio (or
+    // any fixed absolute ceiling) still costs orders of magnitude more than a
+    // rebuild on a big enough repository. 800 documents with 239 stale — 29.875%,
+    // just under the ratio — measured 90.6 s with a 39.6 s synchronous block
+    // against 1.3 s / 10.6 ms for a full build, and at the 6,000-file cap up to
+    // 1,799 stale documents would have stayed on that path.
+    //
+    // So compare estimated WORK, both sides denominated in tokenizer tokens:
+    //   incremental ≈ stale x (docTokens x postingLength x scanCost + readCost)
+    //   full        ≈ totalTokens + corpusSize x readCost
+    // This is self-bounding in a way no constant is: the incremental path is taken
+    // only while its total estimated cost stays under ONE full rebuild, so the
+    // worst case is "about as expensive as rebuilding", whatever the corpus size.
+    //
+    // Both statistics come from cheap metadata passes — one over `postings`
+    // (distinct tokens, reading only `.length`) and one over `forward` (documents,
+    // reading only `.size`). Neither touches a posting ELEMENT, which is the work
+    // this decision exists to avoid.
+    let postingEntries = 0;
+    let weightedPostingEntries = 0;
+    for (const hits of index.postings.values()) {
+        postingEntries += hits.length;
+        weightedPostingEntries += hits.length * hits.length;
+    }
+    // The mean posting-array length weighted by OCCURRENCES, not the plain mean:
+    // a document's tokens are drawn from the frequency distribution, so the arrays
+    // a removal actually filters skew hard toward the high-document-frequency
+    // tokens. The unweighted mean (dominated by the long tail of df=1 tokens)
+    // underestimates the real cost by an order of magnitude.
+    const expectedPostingLength = postingEntries > 0 ? weightedPostingEntries / postingEntries : 0;
+    let distinctTokenEntries = 0;
+    for (const tokenLineCounts of index.forward.values()) {
+        distinctTokenEntries += tokenLineCounts.size;
+    }
+    const expectedDocumentTokens = index.docCount > 0 ? distinctTokenEntries / index.docCount : 0;
+    const estimatedIncrementalWork = staleDocuments *
+        (expectedDocumentTokens *
+            expectedPostingLength *
+            WORD_INDEX_POSTING_SCAN_TOKEN_COST +
+            WORD_INDEX_FILE_READ_TOKEN_COST);
+    const estimatedFullRebuildWork = index.totalTokens + current.size * WORD_INDEX_FILE_READ_TOKEN_COST;
+    // The document-count floor guards the RATIO test only — its documented job is
+    // that "one stale file in a three-file project" is 33% but not dense. It must
+    // NOT gate the work test: a floor is another constant, and letting one
+    // suppress the work comparison would reintroduce exactly the unbounded-on-the
+    // -other-axis shape (31 documents at 98 ms each on this repository's own
+    // corpus, and worse as the corpus grows). The work test needs no floor — on a
+    // small project a full rebuild is cheap, so it never fires there.
+    if ((staleDocuments >= WORD_INDEX_DENSE_REFRESH_MIN_DOCUMENTS &&
+        staleDocuments / Math.max(current.size, 1) >
+            WORD_INDEX_INCREMENTAL_CHURN_THRESHOLD) ||
+        estimatedIncrementalWork > estimatedFullRebuildWork) {
+        return {
+            mode: "full-required",
+            reason: "stale-document-churn",
+            preflightFiles,
+        };
     }
     let dropped = 0;
     for (const key of oldSet) {
         if (!current.has(key)) {
             // `key` is already folded; removeWordIndexDocument re-folds it
             // idempotently via the PathKeyedMap, so the drop hits the right entry.
-            if (!removeWordIndexDocument(index, key)) {
+            if (!(await removeWordIndexDocumentAsync(index, key, shouldContinue))) {
                 throw new Error(`failed to drop word-index document: ${key}`);
             }
             dropped++;
@@ -383,9 +682,16 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
     }
     let refreshed = 0;
     let skipped = 0;
-    let processed = 0;
-    for (const { path: file, mtimeMs } of current.values()) {
-        if (index.fileMtimes.get(file) !== mtimeMs) {
+    for (const { path: file, mtimeMs, size } of current.values()) {
+        // #1105: mtime-first, size-second freshness — mtime alone is a stale
+        // signal (mtime-preserving content changes serve stale identifiers to
+        // symbol_search). Size is free (the stat above already read it) and
+        // catches every content change that alters byte length. Both come from the
+        // SAME stat, so a mismatch on EITHER axis re-reads. `?? -1` makes a file
+        // absent from the (possibly legacy, pre-#1105) size map always count as
+        // changed → one-time re-read that repopulates the size, the safe direction.
+        if (index.fileMtimes.get(file) !== mtimeMs ||
+            (index.fileSizes.get(file) ?? -1) !== size) {
             // A file the walk/stat pass saw can still fail to read here — a
             // transient exclusive lock (antivirus, an editor, a build step) or a
             // file that vanished in the interim. Match collectWordIndexDocs'
@@ -400,14 +706,22 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
                 skipped++;
                 continue;
             }
-            if (!updateWordIndexDocument(index, { path: file, content })) {
+            if (!(await updateWordIndexDocumentAsync(index, { path: file, content }, shouldContinue))) {
                 throw new Error(`failed to refresh word-index document: ${file}`);
             }
+            // updateWordIndexDocument stamps mtime=-1 (per-edit convention); the
+            // refresh path KNOWS the real on-disk stat, so overwrite both axes with
+            // the true values so this document is not needlessly re-read next pass.
             index.fileMtimes.set(file, mtimeMs);
+            index.fileSizes.set(file, size);
             refreshed++;
         }
-        if (++processed % 100 === 0) {
-            await new Promise((resolve) => setImmediate(resolve));
+        // Same OR as the stat loop. This is the loop the #1197 outage actually
+        // blocked in: replacing one document costs more the larger the corpus is,
+        // so a count-only checkpoint let 100 replacements run back to back for
+        // seconds. The gate above keeps the stale set sparse; this keeps even a
+        // sparse-but-expensive set off the event loop.
+        if (deadline.expired() && (await yieldIfOverBudget(deadline))) {
             if (!shouldContinue())
                 throw new Error("word index refresh superseded");
         }
@@ -510,6 +824,8 @@ export function centralityFromReverseDeps(index, reverseDeps, normalizeKey = (fi
     }
     return centrality;
 }
+/** Persisted word-index serialization format version. Bump on breaking format changes. */
+export const WORD_INDEX_FORMAT_VERSION = 2;
 export function serializeWordIndex(index) {
     const files = [...index.docLengths.keys()];
     const fileIndex = new Map();
@@ -533,7 +849,7 @@ export function serializeWordIndex(index) {
         ])
         : undefined;
     return {
-        version: 2,
+        version: WORD_INDEX_FORMAT_VERSION,
         files,
         postings,
         docLengths: files.map((file) => index.docLengths.get(file) ?? 0),
@@ -541,12 +857,13 @@ export function serializeWordIndex(index) {
         indexedFileCount: index.docCount,
         truncated: index.truncated,
         fileMtimes: files.map((file) => index.fileMtimes.get(file) ?? 0),
+        fileSizes: files.map((file) => index.fileSizes.get(file) ?? 0),
         forward,
     };
 }
 export function deserializeWordIndex(data) {
     if (!data ||
-        data.version !== 2 ||
+        data.version !== WORD_INDEX_FORMAT_VERSION ||
         !Array.isArray(data.files) ||
         !Array.isArray(data.postings) ||
         !Array.isArray(data.docLengths) ||
@@ -556,8 +873,17 @@ export function deserializeWordIndex(data) {
     }
     const docLengths = new PathKeyedMap(wordIndexKey);
     const fileMtimes = new PathKeyedMap(wordIndexKey);
+    const fileSizes = new PathKeyedMap(wordIndexKey);
     data.files.forEach((file, i) => docLengths.set(file, data.docLengths[i] ?? 0));
     data.files.forEach((file, i) => fileMtimes.set(file, data.fileMtimes[i] ?? 0));
+    // #1105: `fileSizes` is optional on the wire (pre-#1105 snapshots omit it).
+    // Only populate when the array is present AND parallel to `files`; otherwise
+    // leave it empty so the refresh gate re-reads every file once to repopulate,
+    // rather than trusting a bogus/misaligned size. Never treated as "current".
+    if (Array.isArray(data.fileSizes) &&
+        data.fileSizes.length === data.files.length) {
+        data.files.forEach((file, i) => fileSizes.set(file, data.fileSizes?.[i] ?? 0));
+    }
     const postings = new Map();
     for (const [token, flat] of data.postings) {
         if (typeof token !== "string" || !Array.isArray(flat))
@@ -603,6 +929,7 @@ export function deserializeWordIndex(data) {
         truncated: data.truncated === true,
         forward,
         fileMtimes,
+        fileSizes,
     };
 }
 const buildStatuses = new Map();
@@ -652,7 +979,7 @@ export function triggerBackgroundWordIndexBuild(cwd, dbg, options = {}) {
         try {
             const { loadProjectSnapshot, saveProjectSnapshot, PROJECT_SNAPSHOT_VERSION } = await import("./project-snapshot.js");
             const docs = await collectWordIndexDocs(key);
-            const index = buildWordIndex(docs);
+            const index = await buildWordIndexAsync(docs);
             const existing = loadProjectSnapshot(key);
             const snapshot = existing ?? {
                 version: PROJECT_SNAPSHOT_VERSION,