Method flush

src/sync/watcher.ts:755–827

* 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;

    try {
      const result = await this.syncFn();
      this.lockRetryCount = 0; // a clean sync clears any contention 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 backoff
        const error = err instanceof Error ? err : new Error(String(err));
        logWarn('Watch sync failed', { error: error.message });
        this.onSyncError?.(error);
      }
      // Failure: leave pendingFiles untouched. Every edit it tracks is
      // still unindexed; the rescheduled sync sees the same set.
    } finally {
      this.syncing = false;

      // If pending files remain (mid-sync events, or this sync failed),
      // schedule another pass. After lock contention, back off exponentially
      // (debounceMs · 2^(n-1), capped) instead of retrying at the normal
      // debounce cadence; a clean sync resets lockRetryCount so normal edits