@gitkraken/core-gitlens 0.1.0

package/src/git/watching/watchService.ts

@@ -0,0 +1,350 @@
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+import type { Event } from '../../utils/event.js';
+import { Emitter } from '../../utils/event.js';
+import { isDescendant, relative } from '../../utils/path.js';
+import type { GitDir, RepositoryChange } from '../models/repository.js';
+import type { WatcherRepoChangeEvent } from './changeEvent.js';
+import type { GitIgnoreFilter } from './gitIgnoreFilter.js';
+import type { FileWatcher, FileWatchingProvider } from './provider.js';
+import { shouldIgnoreWorkingTreePath } from './watcherPatterns.js';
+import type { WatchGroupHooks } from './watchGroup.js';
+import { WatchGroup } from './watchGroup.js';
+import { RepositoryWatchSession } from './watchSession.js';
+
+export interface WatchServiceOptions {
+	readonly watchingProvider: FileWatchingProvider;
+	/** Default debounce for repo changes when subscriber doesn't specify. Default: 250ms */
+	readonly defaultRepoDelayMs?: number;
+	/** Default debounce for working tree changes when subscriber doesn't specify. Default: 2500ms */
+	readonly defaultWorkingTreeDelayMs?: number;
+	/** Returns a GitIgnoreFilter for a given repo. When absent or returns undefined, gitignore filtering is skipped. */
+	readonly getIgnoreFilter?: (repoPath: string, gitDirPath: string) => GitIgnoreFilter | undefined;
+}
+
+export interface WatchHooks {
+	/** Called when FETCH_HEAD changed (for last-fetched tracking) */
+	readonly onFetchHeadChanged?: (repoPath: string) => void;
+	/** Called when .git/info/exclude changed */
+	readonly onIgnoresChanged?: (repoPath: string) => void;
+	/** Called when .gitignore changed in the working tree (extension watches this separately) */
+	readonly onGitIgnoreChanged?: (repoPath: string) => void;
+}
+
+export interface WatchHandle {
+	readonly session: RepositoryWatchSession;
+	dispose(): void;
+}
+
+interface SessionRecord {
+	readonly session: RepositoryWatchSession;
+	readonly gitDir: GitDir;
+	readonly watchHooks?: WatchHooks;
+	refCount: number;
+}
+
+/**
+ * Global service that multiplexes repository watching across all repos.
+ *
+ * Manages:
+ * - Session map: one `RepositoryWatchSession` per repo path (ref-counted)
+ * - Watch groups: shared `.git` watchers across worktrees
+ * - Working tree watchers: per-repo filesystem watchers with gitignore filtering
+ *
+ * Sessions and watch groups are created lazily on first `subscribe()`
+ * within a session, and destroyed when the last subscriber leaves.
+ */
+export class RepositoryWatchService implements UnifiedDisposable {
+	private readonly _onDidChangeRepository = new Emitter<WatcherRepoChangeEvent>();
+	/** Global multiplexed event for ALL watched repos */
+	get onDidChangeRepository(): Event<WatcherRepoChangeEvent> {
+		return this._onDidChangeRepository.event;
+	}
+
+	private readonly defaultRepoDelayMs?: number;
+	private readonly defaultWorkingTreeDelayMs?: number;
+	private readonly getIgnoreFilter?: (repoPath: string, gitDirPath: string) => GitIgnoreFilter | undefined;
+	private readonly provider: FileWatchingProvider;
+
+	private readonly sessionMap = new Map<string, SessionRecord>();
+	private readonly watchGroups = new Map<string, WatchGroup>();
+	private readonly wtWatchers = new Map<string, { watcher: FileWatcher; filter?: GitIgnoreFilter }>();
+	private _disposed = false;
+
+	constructor(options: WatchServiceOptions) {
+		this.provider = options.watchingProvider;
+		this.defaultRepoDelayMs = options.defaultRepoDelayMs;
+		this.defaultWorkingTreeDelayMs = options.defaultWorkingTreeDelayMs;
+		this.getIgnoreFilter = options.getIgnoreFilter;
+	}
+
+	[Symbol.dispose](): void {
+		this.dispose();
+	}
+
+	dispose(): void {
+		if (this._disposed) return;
+		this._disposed = true;
+
+		for (const record of this.sessionMap.values()) {
+			this.disposeSessionRecord(record);
+		}
+		this.sessionMap.clear();
+
+		for (const group of this.watchGroups.values()) {
+			group.dispose();
+		}
+		this.watchGroups.clear();
+
+		for (const entry of this.wtWatchers.values()) {
+			entry.watcher.dispose();
+		}
+		this.wtWatchers.clear();
+
+		this._onDidChangeRepository.dispose();
+	}
+
+	/**
+	 * Start watching a repository. Reference-counted:
+	 * same repoPath → same session (refCount++).
+	 * Worktrees sharing a .git dir share the WatchGroup.
+	 *
+	 * Returns a handle with the session and a dispose function.
+	 * Disposing the handle decrements the ref count.
+	 */
+	watch(repoPath: string, gitDir: GitDir, watchHooks?: WatchHooks): WatchHandle | undefined {
+		if (this._disposed) return undefined;
+
+		let record = this.sessionMap.get(repoPath);
+		if (record != null) {
+			record.refCount++;
+		} else {
+			const session = new RepositoryWatchSession({
+				repoPath: repoPath,
+				defaultRepoDelayMs: this.defaultRepoDelayMs,
+				defaultWorkingTreeDelayMs: this.defaultWorkingTreeDelayMs,
+				lifecycle: {
+					onFirstRepoSubscriber: (): void => {
+						const rec = this.sessionMap.get(repoPath);
+						if (rec != null) {
+							this.connectToWatchGroup(rec);
+						}
+					},
+					onLastRepoSubscriber: (): void => {
+						const rec = this.sessionMap.get(repoPath);
+						if (rec != null) {
+							this.disconnectFromWatchGroup(rec);
+						}
+					},
+					onFirstWorkingTreeSubscriber: (): void => {
+						const rec = this.sessionMap.get(repoPath);
+						if (rec != null) {
+							this.startWorkingTreeWatcher(rec);
+						}
+					},
+					onLastWorkingTreeSubscriber: (): void => {
+						this.stopWorkingTreeWatcher(repoPath);
+					},
+				},
+				onDidFireRepoChange: (event): void => {
+					this._onDidChangeRepository.fire(event);
+				},
+			});
+
+			record = {
+				session: session,
+				gitDir: gitDir,
+				watchHooks: watchHooks,
+				refCount: 1,
+			};
+			this.sessionMap.set(repoPath, record);
+		}
+
+		const sessionRef = record.session;
+		let handleDisposed = false;
+
+		return {
+			session: sessionRef,
+			dispose: (): void => {
+				if (handleDisposed) return;
+				handleDisposed = true;
+
+				const rec = this.sessionMap.get(repoPath);
+				if (rec == null) return;
+
+				rec.refCount--;
+				if (rec.refCount <= 0) {
+					this.sessionMap.delete(repoPath);
+					this.disposeSessionRecord(rec);
+				}
+			},
+		};
+	}
+
+	/** Get an existing session by repo path */
+	getSession(repoPath: string): RepositoryWatchSession | undefined {
+		return this.sessionMap.get(repoPath)?.session;
+	}
+
+	/** Suspend all sessions */
+	suspendAll(): void {
+		for (const record of this.sessionMap.values()) {
+			record.session.suspend();
+		}
+	}
+
+	/** Resume all sessions, with optional per-session delay */
+	resumeAll(getDelay?: (session: RepositoryWatchSession) => number): void {
+		for (const record of this.sessionMap.values()) {
+			const delayMs = getDelay?.(record.session);
+			record.session.resume(delayMs);
+		}
+	}
+
+	private getOrCreateWatchGroup(commonGitDir: string): WatchGroup {
+		let group = this.watchGroups.get(commonGitDir);
+		if (group == null) {
+			group = new WatchGroup(commonGitDir, this.provider);
+			this.watchGroups.set(commonGitDir, group);
+		}
+		return group;
+	}
+
+	private maybeDisposeWatchGroup(commonGitDir: string): void {
+		const group = this.watchGroups.get(commonGitDir);
+		if (group == null) return;
+
+		if (group.sessions.size === 0) {
+			group.dispose();
+			this.watchGroups.delete(commonGitDir);
+		}
+	}
+
+	private connectToWatchGroup(record: SessionRecord): void {
+		const { session, gitDir, watchHooks } = record;
+		const commonGitDir = (gitDir.commonUri ?? gitDir.uri).fsPath;
+		const group = this.getOrCreateWatchGroup(commonGitDir);
+
+		const hooks: WatchGroupHooks = {
+			onRepoChanged: function (_repoPath: string, changes: RepositoryChange[]): void {
+				session.pushRepoChanges(changes);
+			},
+			onFetchHeadChanged: function (repoPath: string): void {
+				watchHooks?.onFetchHeadChanged?.(repoPath);
+			},
+			onIgnoresChanged: (repoPath: string): void => {
+				this.refreshWorkingTreeFilter(repoPath);
+				watchHooks?.onIgnoresChanged?.(repoPath);
+			},
+		};
+
+		group.addSession(session.repoPath, gitDir, hooks);
+	}
+
+	private disconnectFromWatchGroup(record: SessionRecord): void {
+		const { session, gitDir } = record;
+		const commonGitDir = (gitDir.commonUri ?? gitDir.uri).fsPath;
+		const group = this.watchGroups.get(commonGitDir);
+		if (group == null) return;
+
+		group.removeSession(session.repoPath);
+		this.maybeDisposeWatchGroup(commonGitDir);
+	}
+
+	private startWorkingTreeWatcher(record: SessionRecord): void {
+		const { session, gitDir, watchHooks } = record;
+		const repoPath = session.repoPath;
+		if (this.wtWatchers.has(repoPath)) return;
+
+		let filter: GitIgnoreFilter | undefined;
+		if (this.getIgnoreFilter != null) {
+			filter = this.getIgnoreFilter(repoPath, gitDir.uri.fsPath);
+		}
+
+		// Buffer events while the gitignore filter loads, then replay
+		let filterReady = filter == null;
+		let buffered: string[] | undefined = filter != null ? [] : undefined;
+
+		if (filter != null) {
+			void filter
+				.ready()
+				.then(() => {
+					filterReady = true;
+					if (buffered?.length) {
+						const paths = filterWorkingTreePaths(buffered, repoPath, filter);
+						if (paths.length > 0) {
+							session.pushWorkingTreeChanges(paths);
+						}
+					}
+					buffered = undefined;
+				})
+				.catch(() => {
+					filterReady = true;
+					buffered = undefined;
+				});
+		}
+
+		const watcher = this.provider.createWatcher(repoPath, '**', event => {
+			// Fast noise check (node_modules, .git, .watchman-cookie-)
+			if (shouldIgnoreWorkingTreePath(event.path)) return;
+
+			// Detect .gitignore changes — refresh the filter and notify the host
+			const relativePath = isDescendant(event.path, repoPath) ? relative(repoPath, event.path) : undefined;
+			if (relativePath === '.gitignore') {
+				if (filter != null) {
+					void filter.refresh();
+				}
+				watchHooks?.onGitIgnoreChanged?.(repoPath);
+				// Don't push .gitignore itself as a working tree change
+				return;
+			}
+
+			if (!filterReady) {
+				// Buffer until gitignore filter is ready
+				buffered?.push(event.path);
+				return;
+			}
+
+			// Gitignore filter (sync after ready)
+			if (filter != null) {
+				if (relativePath != null && filter.isIgnored(relativePath)) return;
+			}
+
+			session.pushWorkingTreeChanges([event.path]);
+		});
+
+		this.wtWatchers.set(repoPath, { watcher: watcher, filter: filter });
+	}
+
+	private stopWorkingTreeWatcher(repoPath: string): void {
+		const entry = this.wtWatchers.get(repoPath);
+		if (entry == null) return;
+
+		entry.watcher.dispose();
+		this.wtWatchers.delete(repoPath);
+	}
+
+	private refreshWorkingTreeFilter(repoPath: string): void {
+		const entry = this.wtWatchers.get(repoPath);
+		if (entry?.filter != null) {
+			void entry.filter.refresh();
+		}
+	}
+
+	private disposeSessionRecord(record: SessionRecord): void {
+		this.disconnectFromWatchGroup(record);
+		this.stopWorkingTreeWatcher(record.session.repoPath);
+		record.session.dispose();
+	}
+}
+
+function filterWorkingTreePaths(absolutePaths: string[], repoPath: string, filter: GitIgnoreFilter): string[] {
+	const result: string[] = [];
+	for (const p of absolutePaths) {
+		if (!isDescendant(p, repoPath)) continue;
+		const relativePath = relative(repoPath, p);
+		if (!filter.isIgnored(relativePath)) {
+			result.push(p);
+		}
+	}
+	return result;
+}

package/src/git/watching/watchSession.ts

@@ -0,0 +1,370 @@
+import type { UnifiedDisposable } from '../../utils/disposable.js';
+import { createDisposable } from '../../utils/disposable.js';
+import type { Event } from '../../utils/event.js';
+import { Emitter } from '../../utils/event.js';
+import type { RepositoryChange } from '../models/repository.js';
+import type { WorkingTreeChangeEvent } from './changeEvent.js';
+import { WatcherRepoChangeEvent } from './changeEvent.js';
+
+export interface RepositorySubscription extends UnifiedDisposable {
+	readonly onDidChange: Event<WatcherRepoChangeEvent>;
+}
+
+export interface WorkingTreeSubscription extends UnifiedDisposable {
+	readonly onDidChangeWorkingTree: Event<WorkingTreeChangeEvent>;
+}
+
+/**
+ * Lifecycle callbacks fired by the session when subscriber counts
+ * cross the 0↔1 boundary. The host (WatchService) uses these to
+ * lazily create/destroy watchers.
+ */
+export interface WatchSessionLifecycle {
+	/** Called when the first repo-change subscriber joins */
+	onFirstRepoSubscriber?(): void;
+	/** Called when the last repo-change subscriber leaves */
+	onLastRepoSubscriber?(): void;
+	/** Called when the first working-tree subscriber joins */
+	onFirstWorkingTreeSubscriber?(): void;
+	/** Called when the last working-tree subscriber leaves */
+	onLastWorkingTreeSubscriber?(): void;
+}
+
+export interface WatchSessionOptions {
+	readonly repoPath: string;
+	/** Default debounce for repo changes. Default: 250ms */
+	readonly defaultRepoDelayMs?: number;
+	/** Default debounce for working tree changes. Default: 2500ms */
+	readonly defaultWorkingTreeDelayMs?: number;
+	readonly lifecycle?: WatchSessionLifecycle;
+	/**
+	 * Called whenever a debounced repo change event is dispatched to subscribers.
+	 * Does NOT count as a subscriber — used by WatchService for
+	 * global event forwarding without affecting lifecycle callbacks.
+	 */
+	readonly onDidFireRepoChange?: (event: WatcherRepoChangeEvent) => void;
+}
+
+const defaultRepoDelay = 250;
+const defaultWorkingTreeDelay = 2500;
+
+/**
+ * Per-repository session that owns the debounce/coalesce/suspend
+ * pipeline for both repo (.git) and working-tree changes.
+ *
+ * Multiple subscribers share the same pipeline — the shortest
+ * requested debounce delay wins.
+ */
+export class RepositoryWatchSession implements UnifiedDisposable {
+	readonly repoPath: string;
+
+	private readonly repoEmitter = new Emitter<WatcherRepoChangeEvent>();
+	private readonly repoDelays = new Map<number, number>(); // subscriberId → delayMs
+	private repoNextId = 0;
+	private pendingRepoEvent: WatcherRepoChangeEvent | undefined;
+	private repoTimer: ReturnType<typeof setTimeout> | undefined;
+	private effectiveRepoMs: number;
+	private readonly defaultRepoMs: number;
+
+	private readonly wtEmitter = new Emitter<WorkingTreeChangeEvent>();
+	private readonly wtDelays = new Map<number, number>();
+	private wtNextId = 0;
+	private pendingWTPaths = new Set<string>();
+	private wtTimer: ReturnType<typeof setTimeout> | undefined;
+	private effectiveWTMs: number;
+	private readonly defaultWTMs: number;
+
+	private _etagWorkingTree = 0;
+	private _suspended = false;
+	private _disposed = false;
+
+	private readonly lifecycle?: WatchSessionLifecycle;
+	private readonly onDidFireRepoChangeCallback?: (event: WatcherRepoChangeEvent) => void;
+
+	constructor(options: WatchSessionOptions) {
+		this.repoPath = options.repoPath;
+		this.defaultRepoMs = options.defaultRepoDelayMs ?? defaultRepoDelay;
+		this.defaultWTMs = options.defaultWorkingTreeDelayMs ?? defaultWorkingTreeDelay;
+		this.effectiveRepoMs = this.defaultRepoMs;
+		this.effectiveWTMs = this.defaultWTMs;
+		this.lifecycle = options.lifecycle;
+		this.onDidFireRepoChangeCallback = options.onDidFireRepoChange;
+	}
+
+	[Symbol.dispose](): void {
+		this.dispose();
+	}
+
+	dispose(): void {
+		if (this._disposed) return;
+		this._disposed = true;
+
+		this.cancelRepoTimer();
+		this.cancelWTTimer();
+
+		this.pendingRepoEvent = undefined;
+		this.pendingWTPaths.clear();
+		this.repoDelays.clear();
+		this.wtDelays.clear();
+
+		this.repoEmitter.dispose();
+		this.wtEmitter.dispose();
+	}
+
+	get suspended(): boolean {
+		return this._suspended;
+	}
+
+	get hasPendingChanges(): boolean {
+		return this.pendingRepoEvent != null || this.pendingWTPaths.size > 0;
+	}
+
+	get repoSubscriberCount(): number {
+		return this.repoDelays.size;
+	}
+
+	get workingTreeSubscriberCount(): number {
+		return this.wtDelays.size;
+	}
+
+	/**
+	 * Monotonic counter incremented immediately when working tree changes
+	 * are pushed (before debounce). Used by `GitCommit.hasFullDetails()`
+	 * to detect staleness of uncommitted commit data.
+	 */
+	get etagWorkingTree(): number {
+		return this._etagWorkingTree;
+	}
+
+	/**
+	 * Subscribe to .git directory changes with configurable debounce.
+	 * First subscribe fires `onFirstRepoSubscriber`, last dispose
+	 * fires `onLastRepoSubscriber`.
+	 *
+	 * When multiple subscribers exist, the shortest debounce wins —
+	 * all subscribers fire on the same (fastest) cadence.
+	 */
+	subscribe(opts?: { delayMs?: number }): RepositorySubscription {
+		if (this._disposed) {
+			return Object.assign(
+				createDisposable(() => {}),
+				{
+					onDidChange: this.repoEmitter.event,
+				},
+			);
+		}
+
+		const id = this.repoNextId++;
+		const delay = opts?.delayMs ?? this.defaultRepoMs;
+		const wasEmpty = this.repoDelays.size === 0;
+		const prevDelay = this.effectiveRepoMs;
+
+		this.repoDelays.set(id, delay);
+		this.recalcRepoDelay();
+
+		if (wasEmpty) {
+			this.lifecycle?.onFirstRepoSubscriber?.();
+		}
+
+		// If the effective delay got shorter while a timer is running, reschedule sooner
+		if (this.effectiveRepoMs < prevDelay && this.repoTimer != null) {
+			this.scheduleRepoFlush();
+		}
+
+		let subDisposed = false;
+		return Object.assign(
+			createDisposable(() => {
+				if (subDisposed) return;
+				subDisposed = true;
+
+				this.repoDelays.delete(id);
+				this.recalcRepoDelay();
+
+				if (this.repoDelays.size === 0) {
+					this.cancelRepoTimer();
+					this.pendingRepoEvent = undefined;
+					this.lifecycle?.onLastRepoSubscriber?.();
+				}
+			}),
+			{ onDidChange: this.repoEmitter.event },
+		);
+	}
+
+	subscribeToWorkingTree(opts?: { delayMs?: number }): WorkingTreeSubscription {
+		if (this._disposed) {
+			return Object.assign(
+				createDisposable(() => {}),
+				{
+					onDidChangeWorkingTree: this.wtEmitter.event,
+				},
+			);
+		}
+
+		const id = this.wtNextId++;
+		const delay = opts?.delayMs ?? this.defaultWTMs;
+		const wasEmpty = this.wtDelays.size === 0;
+		const prevDelay = this.effectiveWTMs;
+
+		this.wtDelays.set(id, delay);
+		this.recalcWTDelay();
+
+		if (wasEmpty) {
+			this.lifecycle?.onFirstWorkingTreeSubscriber?.();
+		}
+
+		// If the effective delay got shorter while a timer is running, reschedule sooner
+		if (this.effectiveWTMs < prevDelay && this.wtTimer != null) {
+			this.scheduleWTFlush();
+		}
+
+		let subDisposed = false;
+		return Object.assign(
+			createDisposable(() => {
+				if (subDisposed) return;
+				subDisposed = true;
+
+				this.wtDelays.delete(id);
+				this.recalcWTDelay();
+
+				if (this.wtDelays.size === 0) {
+					this.cancelWTTimer();
+					this.pendingWTPaths.clear();
+					this.lifecycle?.onLastWorkingTreeSubscriber?.();
+				}
+			}),
+			{ onDidChangeWorkingTree: this.wtEmitter.event },
+		);
+	}
+
+	suspend(): void {
+		this._suspended = true;
+		// Cancel active timers — events continue to coalesce but don't fire
+		this.cancelRepoTimer();
+		this.cancelWTTimer();
+	}
+
+	resume(delayMs?: number): void {
+		if (!this._suspended) return;
+		this._suspended = false;
+
+		// Flush accumulated changes
+		if (this.pendingRepoEvent != null) {
+			this.scheduleRepoFlush(delayMs);
+		}
+		if (this.pendingWTPaths.size > 0) {
+			this.scheduleWTFlush(delayMs);
+		}
+	}
+
+	/** Inject changes (e.g., after a git operation the caller performed). Goes through debounce + suspend. */
+	fireChange(...changes: RepositoryChange[]): void {
+		if (this._disposed || changes.length === 0) return;
+		this.coalesceRepo(changes);
+	}
+
+	/** Immediate fire, bypassing debounce + suspend (for Closed/Opened). */
+	fireChangeImmediate(...changes: RepositoryChange[]): void {
+		if (this._disposed || changes.length === 0) return;
+		this.repoEmitter.fire(new WatcherRepoChangeEvent(this.repoPath, changes));
+	}
+
+	/** Push interpreted repo changes into the pipeline */
+	pushRepoChanges(changes: RepositoryChange[]): void {
+		if (this._disposed) return;
+		this.coalesceRepo(changes);
+	}
+
+	/** Push working tree file changes into the pipeline */
+	pushWorkingTreeChanges(paths: Iterable<string>): void {
+		if (this._disposed) return;
+		this._etagWorkingTree++;
+		this.coalesceWT(paths);
+	}
+
+	private static minDelay(delays: Map<number, number>, fallback: number): number {
+		if (delays.size === 0) return fallback;
+		let min = fallback;
+		for (const d of delays.values()) {
+			if (d < min) {
+				min = d;
+			}
+		}
+		return min;
+	}
+
+	private recalcRepoDelay(): void {
+		this.effectiveRepoMs = RepositoryWatchSession.minDelay(this.repoDelays, this.defaultRepoMs);
+	}
+
+	private recalcWTDelay(): void {
+		this.effectiveWTMs = RepositoryWatchSession.minDelay(this.wtDelays, this.defaultWTMs);
+	}
+
+	private flushRepo(): void {
+		this.repoTimer = undefined;
+		const event = this.pendingRepoEvent;
+		if (event == null) return;
+		this.pendingRepoEvent = undefined;
+		this.repoEmitter.fire(event);
+		this.onDidFireRepoChangeCallback?.(event);
+	}
+
+	private scheduleRepoFlush(delayOverride?: number): void {
+		if (this._suspended || this.pendingRepoEvent == null) return;
+
+		if (this.repoTimer != null) {
+			clearTimeout(this.repoTimer);
+		}
+		this.repoTimer = setTimeout(() => this.flushRepo(), delayOverride ?? this.effectiveRepoMs);
+	}
+
+	private coalesceRepo(changes: RepositoryChange[]): void {
+		if (changes.length === 0) return;
+
+		this.pendingRepoEvent =
+			this.pendingRepoEvent == null
+				? new WatcherRepoChangeEvent(this.repoPath, changes)
+				: this.pendingRepoEvent.with(changes);
+
+		this.scheduleRepoFlush();
+	}
+
+	private flushWT(): void {
+		this.wtTimer = undefined;
+		if (this.pendingWTPaths.size === 0) return;
+
+		const paths = this.pendingWTPaths;
+		this.pendingWTPaths = new Set();
+		this.wtEmitter.fire({ repoPath: this.repoPath, paths: paths });
+	}
+
+	private scheduleWTFlush(delayOverride?: number): void {
+		if (this._suspended || this.pendingWTPaths.size === 0) return;
+
+		if (this.wtTimer != null) {
+			clearTimeout(this.wtTimer);
+		}
+		this.wtTimer = setTimeout(() => this.flushWT(), delayOverride ?? this.effectiveWTMs);
+	}
+
+	private coalesceWT(paths: Iterable<string>): void {
+		for (const p of paths) {
+			this.pendingWTPaths.add(p);
+		}
+		this.scheduleWTFlush();
+	}
+
+	private cancelRepoTimer(): void {
+		if (this.repoTimer != null) {
+			clearTimeout(this.repoTimer);
+			this.repoTimer = undefined;
+		}
+	}
+
+	private cancelWTTimer(): void {
+		if (this.wtTimer != null) {
+			clearTimeout(this.wtTimer);
+			this.wtTimer = undefined;
+		}
+	}
+}