Method flush

src/sync/watcher.ts:838–945

* Flush pending changes by running sync. * * pendingFiles is NOT cleared at the start of sync — entries are removed * only after sync commits successfully, and only for entries whose * lastSeenMs <= syncStartedMs. That way, a query that arrives mid-sync * still sees the affected files

()

   * unindexed, and the rescheduled sync will absorb the same set next time.
   */
  private async flush(): Promise<void> {
    // If already syncing, the post-sync check will re-trigger
    if (this.syncing || this.stopped) return;

    this.syncStartedMs = Date.now();
    this.syncing = true;

    // Scoped fast path: when every pending change is a known file event, hand
    // the exact paths to sync and skip its O(repo) scan-diff. Anything the
    // events can't fully describe — a directory removal, an empty pending set
    // (retry paths), or an event storm past the ceiling — runs the full
    // scan-diff, which remains the ground truth.
    const scoped =
      !this.needsFullScan && this.pendingFiles.size > 0 && this.pendingFiles.size <= SCOPED_SYNC_MAX_PENDING
        ? [...this.pendingFiles.keys()]
        : undefined;

    try {
      const result = await this.syncFn(scoped);
      if (!scoped) this.needsFullScan = false;
      this.lockRetryCount = 0; // a clean sync clears any contention backoff
      this.syncFailureRetryCount = 0; // ...and any generic-failure backoff
      // Remove entries whose most recent event predates this sync — those
      // edits are now in the DB. Entries with lastSeenMs > syncStartedMs
      // arrived mid-sync; whether the in-flight sync captured them depends
      // on when sync read that file, so we keep them as pending and let
      // the follow-up sync handle them. We prefer false positives ("shown
      // stale, actually fresh" → at worst one extra Read) over false
      // negatives ("shown fresh, actually stale" → misleads the agent).
      for (const [filePath, info] of this.pendingFiles) {
        if (info.lastSeenMs <= this.syncStartedMs) {
          this.pendingFiles.delete(filePath);
        }
      }
      this.onSyncComplete?.(result);
    } catch (err) {
      if (err instanceof LockUnavailableError) {
        this.lockRetryCount += 1;
        // Lock-failure no-op (another writer holds the lock). pendingFiles
        // stays intact and the `finally` block reschedules with backoff. Keep
        // brief contention quiet (debug-only — a long external index would
        // otherwise spam stderr every cycle), but stop retrying forever: once a
        // writer holds the lock past the budget, degrade auto-sync explicitly.
        logDebug('Watch sync skipped: file lock unavailable', {
          pendingFiles: this.pendingFiles.size,
          retryCount: this.lockRetryCount,
        });
        if (this.lockRetryCount > MAX_LOCK_RETRIES) {
          this.degrade(
            'CodeGraph file lock held by another process past the retry budget; ' +
              'auto-sync disabled. Run `codegraph sync` once the other writer finishes ' +
              '(or install git sync hooks) to refresh the graph.',
            { pendingFiles: this.pendingFiles.size, retryCount: this.lockRetryCount }
          );
        }
      } else {
        this.lockRetryCount = 0; // a non-lock failure isn't contention; reset that streak
        this.syncFailureRetryCount += 1;