@gitkraken/core-gitlens 0.10.6 → 0.11.0

package/dist/git/watching/watchSession.d.ts

@@ -30,6 +30,13 @@ export interface WatchSessionOptions {
   readonly defaultRepoDelayMs?: number;
   /** Default debounce for working tree changes. Default: 2500ms */
   readonly defaultWorkingTreeDelayMs?: number;
+  /**
+   * Default cap on how long repo changes can be held back by continuous activity — a flush happens at most this long
+   * after the first pending change, however long the burst lasts. `Infinity` disables the cap. Default: 2000ms
+   */
+  readonly defaultRepoMaxWaitMs?: number;
+  /** Default cap on how long working tree changes can be held back by continuous activity. `Infinity` disables the cap. Default: 10000ms */
+  readonly defaultWorkingTreeMaxWaitMs?: number;
   readonly lifecycle?: WatchSessionLifecycle;
   /** Initial suspended state — new sessions inherit the service-global suspend state. Default: false */
   readonly suspended?: boolean;
@@ -51,25 +58,33 @@ export interface WatchSessionOptions {
  * pipeline for both repo (.git) and working-tree changes.
  *
  * Multiple subscribers share the same pipeline — the shortest
- * requested debounce delay wins.
+ * requested debounce delay wins, and so does the shortest max-wait.
  */
 export declare class RepositoryWatchSession implements UnifiedDisposable {
   readonly repoPath: string;
   private readonly repoEmitter;
-  private readonly repoDelays;
+  private readonly repoSubscribers;
   private repoNextId;
-  private pendingRepoEvent;
-  private repoTimer;
+  private readonly pendingRepoChanges;
+  /** Full ref names, ref directories and pseudo-refs whose files changed, flushed with {@link pendingRepoChanges} */
+  private readonly pendingRepoRefs;
+  /** Ref kinds that changed without a name, flushed with {@link pendingRepoChanges} */
+  private readonly pendingRepoUnnamedRefKinds;
+  private readonly repoClock;
   private effectiveRepoMs;
+  private effectiveRepoMaxWaitMs;
   private readonly defaultRepoMs;
+  private readonly defaultRepoMaxWaitMs;
   private readonly workingTreeEmitter;
-  private readonly workingTreeDelays;
+  private readonly workingTreeSubscribers;
   private workingTreeNextId;
   private pendingWorkingTreePaths;
   private pendingWorkingTreeIncomplete;
-  private workingTreeTimer;
+  private readonly workingTreeClock;
   private effectiveWorkingTreeMs;
+  private effectiveWorkingTreeMaxWaitMs;
   private readonly defaultWorkingTreeMs;
+  private readonly defaultWorkingTreeMaxWaitMs;
   private _etagWorkingTree;
   private _suspended;
   private _disposed;
@@ -100,36 +115,54 @@ export declare class RepositoryWatchSession implements UnifiedDisposable {
    * fires `onLastRepoSubscriber`.
    *
    * When multiple subscribers exist, the shortest debounce wins —
-   * all subscribers fire on the same (fastest) cadence.
+   * all subscribers fire on the same (fastest) cadence. `maxWaitMs` bounds how long continuous
+   * activity can defer a flush (the shortest wins too); `Infinity` means no cap.
+   *
+   * `relevantRefs` narrows THIS subscription's events to the refs it cares about, given as full ref names
+   * (`refs/heads/main`, `refs/remotes/origin/main`, `refs/tags/v1`, `refs/stash`). It is read at delivery, so it can
+   * return the subscriber's current list. A `heads`/`remotes`/`tags`/`stash` change is delivered only when a listed
+   * ref of that kind may have moved, when the change isn't attributable to a name (e.g. a `packed-refs` rewrite),
+   * or, for `heads`, when a pseudo-ref (`HEAD`, `ORIG_HEAD`) moved — so `stash` and `tags` changes are dropped unless
+   * a ref of that kind is listed. Other change kinds always pass, and an event left with no changes isn't delivered.
+   * The filter never affects other subscribers, the debounce, or the global `onDidFireRepoChange` forwarding.
    */
   subscribe(opts?: {
     delayMs?: number;
+    maxWaitMs?: number;
+    relevantRefs?: () => Iterable<string>;
   }): RepositorySubscription;
+  /** Subscribe to working tree changes; `delayMs` and `maxWaitMs` behave as in {@link subscribe}. */
   subscribeToWorkingTree(opts?: {
     delayMs?: number;
+    maxWaitMs?: number;
   }): WorkingTreeSubscription;
   suspend(): void;
   resume(delayMs?: number): void;
-  /** Inject changes (e.g., after a git operation the caller performed). Goes through debounce + suspend. */
+  /**
+   * Inject changes (e.g., after a git operation the caller performed). Goes through debounce + suspend. Ref kinds
+   * among them are unnamed — any ref of that kind may have moved.
+   */
   fireChange(...changes: RepositoryChange[]): void;
-  /** Immediate fire, bypassing debounce + suspend (for Closed/Opened). */
+  /** Immediate fire, bypassing debounce + suspend (for Closed/Opened). Ref kinds among them are unnamed. */
   fireChangeImmediate(...changes: RepositoryChange[]): void;
-  /** Push interpreted repo changes into the pipeline */
-  pushRepoChanges(changes: RepositoryChange[]): void;
+  /**
+   * Push interpreted repo changes into the pipeline. `ref` is the full ref name (or ref directory, or pseudo-ref) whose
+   * file changed; a ref kind in `changes` is attributed to it when the kinds match, and is otherwise unnamed.
+   */
+  pushRepoChanges(changes: RepositoryChange[], ref?: string): void;
   /** Push working tree file changes into the pipeline */
   /** `incomplete` marks the batch as partial when the caller already dropped paths of its own. */
   pushWorkingTreeChanges(paths: Iterable<string>, incomplete?: boolean): void;
   private static minDelay;
-  private recalcRepoDelay;
-  private recalcWorkingTreeDelay;
+  /** Unlike the delay, the default isn't a ceiling — a subscriber can opt out of the cap with `Infinity` */
+  private static minMaxWait;
+  private recalcRepoTiming;
+  private recalcWorkingTreeTiming;
   private flushRepo;
-  private scheduleRepoFlush;
   private coalesceRepo;
+  private clearPendingRepoChanges;
   private flushWorkingTree;
-  private scheduleWorkingTreeFlush;
   private coalesceWorkingTrees;
-  private cancelRepoTimer;
-  private cancelWorkingTreeTimer;
 }
 //#endregion
 //# sourceMappingURL=watchSession.d.ts.map

package/dist/git/watching/watchSession.js

@@ -1,9 +1,113 @@
 import { createDisposable } from "../../utils/disposable.js";
 import { Emitter } from "../../utils/event.js";
-import { WatcherRepoChangeEvent } from "./changeEvent.js";
+import { WatcherRepoChangeEvent, findCoveringRefName, getRefChangeKind, isRefChangeKind } from "./changeEvent.js";
 //#region ../git/src/watching/watchSession.ts
 const defaultRepoDelay = 250;
 const defaultWorkingTreeDelay = 2500;
+const defaultRepoMaxWait = 2e3;
+const defaultWorkingTreeMaxWait = 1e4;
+/** Largest delay `setTimeout` honors (a signed 32-bit int); anything longer fires immediately */
+const maxTimerDelay = 2147483647;
+/**
+* Trailing-deadline debounce with a max-wait, shared by the repo and working-tree pipelines.
+*
+* Recording an event costs a `performance.now()` and, only when no timer is armed, one `setTimeout` — never a
+* `clearTimeout`/`setTimeout` pair per event, which is what made a busy repo allocate (and starve) on every raw
+* watcher event. The armed timer is a deadline, not a countdown: when it fires it recomputes the due time from the
+* latest timestamps and either flushes or re-arms for the remainder. The due time is
+* `min(lastEventAt + delay, firstPendingAt + maxWait)`, so continuous activity is flushed at the max-wait instead of
+* never. Monotonic time, so a wall-clock change can't push a deadline out.
+*/
+var DebounceClock = class {
+	getDelayMs;
+	getMaxWaitMs;
+	onDue;
+	active = false;
+	paused = false;
+	firstAt = 0;
+	lastAt = 0;
+	timer;
+	timerDueAt = 0;
+	/** Absolute flush time set by {@link resume}; dropped by the next event, which returns to normal debounce */
+	resumeDueAt;
+	constructor(getDelayMs, getMaxWaitMs, onDue) {
+		this.getDelayMs = getDelayMs;
+		this.getMaxWaitMs = getMaxWaitMs;
+		this.onDue = onDue;
+	}
+	/** Records an event; arms the timer only if none is armed. Cheap enough to call per raw event. */
+	note() {
+		const now = performance.now();
+		if (!this.active) {
+			this.active = true;
+			this.firstAt = now;
+		}
+		this.lastAt = now;
+		if (this.paused) return;
+		if (this.resumeDueAt != null) {
+			this.resumeDueAt = void 0;
+			this.rearmIfEarlier();
+		}
+		if (this.timer == null) this.arm(this.getDueAt(), now);
+	}
+	/** Moves the armed timer earlier when the due time shrank (a subscriber joined with a shorter delay or max-wait) */
+	rearmIfEarlier() {
+		if (!this.active || this.paused || this.timer == null) return;
+		const dueAt = this.getDueAt();
+		if (dueAt >= this.timerDueAt) return;
+		clearTimeout(this.timer);
+		this.arm(dueAt, performance.now());
+	}
+	/** Cancels the timer; events keep accumulating but nothing is due until {@link resume} */
+	suspend() {
+		this.paused = true;
+		this.clearTimer();
+	}
+	/**
+	* Restarts the max-wait window from now and schedules the flush for `delayMs` from now (the effective delay when
+	* omitted). Does nothing if no events are pending.
+	*/
+	resume(delayMs) {
+		this.paused = false;
+		if (!this.active) return;
+		const now = performance.now();
+		this.firstAt = now;
+		this.resumeDueAt = now + (delayMs ?? this.getDelayMs());
+		this.clearTimer();
+		this.arm(this.resumeDueAt, now);
+	}
+	/** Drops the pending window and the timer */
+	cancel() {
+		this.active = false;
+		this.resumeDueAt = void 0;
+		this.clearTimer();
+	}
+	getDueAt() {
+		return this.resumeDueAt ?? Math.min(this.lastAt + this.getDelayMs(), this.firstAt + this.getMaxWaitMs());
+	}
+	arm(dueAt, now) {
+		this.timerDueAt = dueAt;
+		this.timer = setTimeout(() => this.onTimer(), Math.min(Math.max(0, dueAt - now), maxTimerDelay));
+	}
+	onTimer() {
+		this.timer = void 0;
+		if (!this.active || this.paused) return;
+		const now = performance.now();
+		const dueAt = this.getDueAt();
+		if (dueAt > now) {
+			this.arm(dueAt, now);
+			return;
+		}
+		this.cancel();
+		this.onDue();
+	}
+	clearTimer() {
+		if (this.timer != null) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+	}
+};
 /**
 * Cap on retained working-tree paths per flush. The set otherwise grows without bound — while the window
 * is unfocused the session is suspended, so a branch switch or build accumulates every touched path until
@@ -13,29 +117,42 @@ const defaultWorkingTreeDelay = 2500;
 */
 const maxWorkingTreePaths = 1e3;
 /**
+* Cap on retained ref names per flush, for the same reason (a fetch of many refs while suspended). Past it, a ref kind
+* is recorded unnamed — any ref of that kind may have moved — which only makes `mayHaveChangedRef` more conservative.
+*/
+const maxPendingRefNames = 1e3;
+/**
 * 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.
+* requested debounce delay wins, and so does the shortest max-wait.
 */
 var RepositoryWatchSession = class RepositoryWatchSession {
 	repoPath;
 	repoEmitter = new Emitter();
-	repoDelays = /* @__PURE__ */ new Map();
+	repoSubscribers = /* @__PURE__ */ new Map();
 	repoNextId = 0;
-	pendingRepoEvent;
-	repoTimer;
+	pendingRepoChanges = /* @__PURE__ */ new Set();
+	/** Full ref names, ref directories and pseudo-refs whose files changed, flushed with {@link pendingRepoChanges} */
+	pendingRepoRefs = /* @__PURE__ */ new Set();
+	/** Ref kinds that changed without a name, flushed with {@link pendingRepoChanges} */
+	pendingRepoUnnamedRefKinds = /* @__PURE__ */ new Set();
+	repoClock;
 	effectiveRepoMs;
+	effectiveRepoMaxWaitMs;
 	defaultRepoMs;
+	defaultRepoMaxWaitMs;
 	workingTreeEmitter = new Emitter();
-	workingTreeDelays = /* @__PURE__ */ new Map();
+	workingTreeSubscribers = /* @__PURE__ */ new Map();
 	workingTreeNextId = 0;
 	pendingWorkingTreePaths = /* @__PURE__ */ new Set();
 	pendingWorkingTreeIncomplete = false;
-	workingTreeTimer;
+	workingTreeClock;
 	effectiveWorkingTreeMs;
+	effectiveWorkingTreeMaxWaitMs;
 	defaultWorkingTreeMs;
+	defaultWorkingTreeMaxWaitMs;
 	_etagWorkingTree = 0;
 	_suspended;
 	_disposed = false;
@@ -46,12 +163,22 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 		this.repoPath = options.repoPath;
 		this.defaultRepoMs = options.defaultRepoDelayMs ?? defaultRepoDelay;
 		this.defaultWorkingTreeMs = options.defaultWorkingTreeDelayMs ?? defaultWorkingTreeDelay;
+		this.defaultRepoMaxWaitMs = options.defaultRepoMaxWaitMs ?? defaultRepoMaxWait;
+		this.defaultWorkingTreeMaxWaitMs = options.defaultWorkingTreeMaxWaitMs ?? defaultWorkingTreeMaxWait;
 		this.effectiveRepoMs = this.defaultRepoMs;
+		this.effectiveRepoMaxWaitMs = this.defaultRepoMaxWaitMs;
 		this.effectiveWorkingTreeMs = this.defaultWorkingTreeMs;
+		this.effectiveWorkingTreeMaxWaitMs = this.defaultWorkingTreeMaxWaitMs;
+		this.repoClock = new DebounceClock(() => this.effectiveRepoMs, () => this.effectiveRepoMaxWaitMs, () => this.flushRepo());
+		this.workingTreeClock = new DebounceClock(() => this.effectiveWorkingTreeMs, () => this.effectiveWorkingTreeMaxWaitMs, () => this.flushWorkingTree());
 		this.lifecycle = options.lifecycle;
 		this.onDidFireRepoChangeCallback = options.onDidFireRepoChange;
 		this.onDidFireWorkingTreeChangeCallback = options.onDidFireWorkingTreeChange;
 		this._suspended = options.suspended ?? false;
+		if (this._suspended) {
+			this.repoClock.suspend();
+			this.workingTreeClock.suspend();
+		}
 	}
 	[Symbol.dispose]() {
 		this.dispose();
@@ -59,13 +186,13 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 	dispose() {
 		if (this._disposed) return;
 		this._disposed = true;
-		this.cancelRepoTimer();
-		this.cancelWorkingTreeTimer();
-		this.pendingRepoEvent = void 0;
+		this.repoClock.cancel();
+		this.workingTreeClock.cancel();
+		this.clearPendingRepoChanges();
 		this.pendingWorkingTreePaths.clear();
 		this.pendingWorkingTreeIncomplete = false;
-		this.repoDelays.clear();
-		this.workingTreeDelays.clear();
+		this.repoSubscribers.clear();
+		this.workingTreeSubscribers.clear();
 		this.repoEmitter.dispose();
 		this.workingTreeEmitter.dispose();
 	}
@@ -73,7 +200,7 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 		return this._suspended;
 	}
 	get hasPendingChanges() {
-		return this.pendingRepoEvent != null || this.hasPendingWorkingTreeChanges;
+		return this.pendingRepoChanges.size > 0 || this.hasPendingWorkingTreeChanges;
 	}
 	/**
 	* An incomplete batch with no surviving paths still has to fire: the caller dropped paths we never saw, so
@@ -83,10 +210,10 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 		return this.pendingWorkingTreePaths.size > 0 || this.pendingWorkingTreeIncomplete;
 	}
 	get repoSubscriberCount() {
-		return this.repoDelays.size;
+		return this.repoSubscribers.size;
 	}
 	get workingTreeSubscriberCount() {
-		return this.workingTreeDelays.size;
+		return this.workingTreeSubscribers.size;
 	}
 	/**
 	* Monotonic counter incremented immediately when working tree changes
@@ -102,49 +229,61 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 	* fires `onLastRepoSubscriber`.
 	*
 	* When multiple subscribers exist, the shortest debounce wins —
-	* all subscribers fire on the same (fastest) cadence.
+	* all subscribers fire on the same (fastest) cadence. `maxWaitMs` bounds how long continuous
+	* activity can defer a flush (the shortest wins too); `Infinity` means no cap.
+	*
+	* `relevantRefs` narrows THIS subscription's events to the refs it cares about, given as full ref names
+	* (`refs/heads/main`, `refs/remotes/origin/main`, `refs/tags/v1`, `refs/stash`). It is read at delivery, so it can
+	* return the subscriber's current list. A `heads`/`remotes`/`tags`/`stash` change is delivered only when a listed
+	* ref of that kind may have moved, when the change isn't attributable to a name (e.g. a `packed-refs` rewrite),
+	* or, for `heads`, when a pseudo-ref (`HEAD`, `ORIG_HEAD`) moved — so `stash` and `tags` changes are dropped unless
+	* a ref of that kind is listed. Other change kinds always pass, and an event left with no changes isn't delivered.
+	* The filter never affects other subscribers, the debounce, or the global `onDidFireRepoChange` forwarding.
 	*/
 	subscribe(opts) {
 		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();
+		const wasEmpty = this.repoSubscribers.size === 0;
+		this.repoSubscribers.set(id, {
+			delayMs: opts?.delayMs ?? this.defaultRepoMs,
+			maxWaitMs: opts?.maxWaitMs ?? this.defaultRepoMaxWaitMs
+		});
+		this.recalcRepoTiming();
 		if (wasEmpty) this.lifecycle?.onFirstRepoSubscriber?.();
-		if (this.effectiveRepoMs < prevDelay && this.repoTimer != null) this.scheduleRepoFlush();
+		this.repoClock.rearmIfEarlier();
 		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 = void 0;
+			this.repoSubscribers.delete(id);
+			this.recalcRepoTiming();
+			if (this.repoSubscribers.size === 0) {
+				this.repoClock.cancel();
+				this.clearPendingRepoChanges();
 				this.lifecycle?.onLastRepoSubscriber?.();
 			}
-		}), { onDidChange: this.repoEmitter.event });
+		}), { onDidChange: opts?.relevantRefs != null ? createRelevantRefsEvent(this.repoEmitter.event, opts.relevantRefs) : this.repoEmitter.event });
 	}
+	/** Subscribe to working tree changes; `delayMs` and `maxWaitMs` behave as in {@link subscribe}. */
 	subscribeToWorkingTree(opts) {
 		if (this._disposed) return Object.assign(createDisposable(() => {}), { onDidChangeWorkingTree: this.workingTreeEmitter.event });
 		const id = this.workingTreeNextId++;
-		const delay = opts?.delayMs ?? this.defaultWorkingTreeMs;
-		const wasEmpty = this.workingTreeDelays.size === 0;
-		const prevDelay = this.effectiveWorkingTreeMs;
-		this.workingTreeDelays.set(id, delay);
-		this.recalcWorkingTreeDelay();
+		const wasEmpty = this.workingTreeSubscribers.size === 0;
+		this.workingTreeSubscribers.set(id, {
+			delayMs: opts?.delayMs ?? this.defaultWorkingTreeMs,
+			maxWaitMs: opts?.maxWaitMs ?? this.defaultWorkingTreeMaxWaitMs
+		});
+		this.recalcWorkingTreeTiming();
 		if (wasEmpty) this.lifecycle?.onFirstWorkingTreeSubscriber?.();
-		if (this.effectiveWorkingTreeMs < prevDelay && this.workingTreeTimer != null) this.scheduleWorkingTreeFlush();
+		this.workingTreeClock.rearmIfEarlier();
 		let subDisposed = false;
 		return Object.assign(createDisposable(() => {
 			if (subDisposed) return;
 			subDisposed = true;
-			this.workingTreeDelays.delete(id);
-			this.recalcWorkingTreeDelay();
-			if (this.workingTreeDelays.size === 0) {
-				this.cancelWorkingTreeTimer();
+			this.workingTreeSubscribers.delete(id);
+			this.recalcWorkingTreeTiming();
+			if (this.workingTreeSubscribers.size === 0) {
+				this.workingTreeClock.cancel();
 				this.pendingWorkingTreePaths.clear();
 				this.pendingWorkingTreeIncomplete = false;
 				this.lifecycle?.onLastWorkingTreeSubscriber?.();
@@ -153,31 +292,37 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 	}
 	suspend() {
 		this._suspended = true;
-		this.cancelRepoTimer();
-		this.cancelWorkingTreeTimer();
+		this.repoClock.suspend();
+		this.workingTreeClock.suspend();
 	}
 	resume(delayMs) {
 		if (!this._suspended) return;
 		this._suspended = false;
-		if (this.pendingRepoEvent != null) this.scheduleRepoFlush(delayMs);
-		if (this.hasPendingWorkingTreeChanges) this.scheduleWorkingTreeFlush(delayMs);
+		this.repoClock.resume(delayMs);
+		this.workingTreeClock.resume(delayMs);
 	}
-	/** Inject changes (e.g., after a git operation the caller performed). Goes through debounce + suspend. */
+	/**
+	* Inject changes (e.g., after a git operation the caller performed). Goes through debounce + suspend. Ref kinds
+	* among them are unnamed — any ref of that kind may have moved.
+	*/
 	fireChange(...changes) {
 		if (this._disposed || changes.length === 0) return;
 		this.coalesceRepo(changes);
 	}
-	/** Immediate fire, bypassing debounce + suspend (for Closed/Opened). */
+	/** Immediate fire, bypassing debounce + suspend (for Closed/Opened). Ref kinds among them are unnamed. */
 	fireChangeImmediate(...changes) {
 		if (this._disposed || changes.length === 0) return;
 		const event = new WatcherRepoChangeEvent(this.repoPath, changes);
 		this.onDidFireRepoChangeCallback?.(event);
 		this.repoEmitter.fire(event);
 	}
-	/** Push interpreted repo changes into the pipeline */
-	pushRepoChanges(changes) {
+	/**
+	* Push interpreted repo changes into the pipeline. `ref` is the full ref name (or ref directory, or pseudo-ref) whose
+	* file changed; a ref kind in `changes` is attributed to it when the kinds match, and is otherwise unnamed.
+	*/
+	pushRepoChanges(changes, ref) {
 		if (this._disposed) return;
-		this.coalesceRepo(changes);
+		this.coalesceRepo(changes, ref);
 	}
 	/** Push working tree file changes into the pipeline */
 	/** `incomplete` marks the batch as partial when the caller already dropped paths of its own. */
@@ -187,38 +332,53 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 		if (incomplete) this.pendingWorkingTreeIncomplete = true;
 		this.coalesceWorkingTrees(paths);
 	}
-	static minDelay(delays, fallback) {
-		if (delays.size === 0) return fallback;
+	static minDelay(subscribers, fallback) {
 		let min = fallback;
-		for (const d of delays.values()) if (d < min) min = d;
+		for (const { delayMs } of subscribers.values()) if (delayMs < min) min = delayMs;
+		return min;
+	}
+	/** Unlike the delay, the default isn't a ceiling — a subscriber can opt out of the cap with `Infinity` */
+	static minMaxWait(subscribers, fallback) {
+		if (subscribers.size === 0) return fallback;
+		let min = Infinity;
+		for (const { maxWaitMs } of subscribers.values()) if (maxWaitMs < min) min = maxWaitMs;
 		return min;
 	}
-	recalcRepoDelay() {
-		this.effectiveRepoMs = RepositoryWatchSession.minDelay(this.repoDelays, this.defaultRepoMs);
+	recalcRepoTiming() {
+		this.effectiveRepoMs = RepositoryWatchSession.minDelay(this.repoSubscribers, this.defaultRepoMs);
+		this.effectiveRepoMaxWaitMs = RepositoryWatchSession.minMaxWait(this.repoSubscribers, this.defaultRepoMaxWaitMs);
 	}
-	recalcWorkingTreeDelay() {
-		this.effectiveWorkingTreeMs = RepositoryWatchSession.minDelay(this.workingTreeDelays, this.defaultWorkingTreeMs);
+	recalcWorkingTreeTiming() {
+		this.effectiveWorkingTreeMs = RepositoryWatchSession.minDelay(this.workingTreeSubscribers, this.defaultWorkingTreeMs);
+		this.effectiveWorkingTreeMaxWaitMs = RepositoryWatchSession.minMaxWait(this.workingTreeSubscribers, this.defaultWorkingTreeMaxWaitMs);
 	}
 	flushRepo() {
-		this.repoTimer = void 0;
-		const event = this.pendingRepoEvent;
-		if (event == null) return;
-		this.pendingRepoEvent = void 0;
+		if (this.pendingRepoChanges.size === 0) return;
+		const event = new WatcherRepoChangeEvent(this.repoPath, [...this.pendingRepoChanges], {
+			names: this.pendingRepoRefs,
+			unnamed: this.pendingRepoUnnamedRefKinds
+		});
+		this.clearPendingRepoChanges();
 		this.onDidFireRepoChangeCallback?.(event);
 		this.repoEmitter.fire(event);
 	}
-	scheduleRepoFlush(delayOverride) {
-		if (this._suspended || this.pendingRepoEvent == null) return;
-		if (this.repoTimer != null) clearTimeout(this.repoTimer);
-		this.repoTimer = setTimeout(() => this.flushRepo(), delayOverride ?? this.effectiveRepoMs);
-	}
-	coalesceRepo(changes) {
+	coalesceRepo(changes, ref) {
 		if (changes.length === 0) return;
-		this.pendingRepoEvent = this.pendingRepoEvent == null ? new WatcherRepoChangeEvent(this.repoPath, changes) : this.pendingRepoEvent.with(changes);
-		this.scheduleRepoFlush();
+		const refKind = ref != null ? getRefChangeKind(ref) : void 0;
+		for (const change of changes) {
+			this.pendingRepoChanges.add(change);
+			if (!isRefChangeKind(change)) continue;
+			if (ref != null && refKind === change && (this.pendingRepoRefs.size < maxPendingRefNames || this.pendingRepoRefs.has(ref))) this.pendingRepoRefs.add(ref);
+			else this.pendingRepoUnnamedRefKinds.add(change);
+		}
+		this.repoClock.note();
+	}
+	clearPendingRepoChanges() {
+		this.pendingRepoChanges.clear();
+		this.pendingRepoRefs.clear();
+		this.pendingRepoUnnamedRefKinds.clear();
 	}
 	flushWorkingTree() {
-		this.workingTreeTimer = void 0;
 		if (!this.hasPendingWorkingTreeChanges) return;
 		const paths = this.pendingWorkingTreePaths;
 		const incomplete = this.pendingWorkingTreeIncomplete;
@@ -231,11 +391,6 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 			incomplete
 		});
 	}
-	scheduleWorkingTreeFlush(delayOverride) {
-		if (this._suspended || !this.hasPendingWorkingTreeChanges) return;
-		if (this.workingTreeTimer != null) clearTimeout(this.workingTreeTimer);
-		this.workingTreeTimer = setTimeout(() => this.flushWorkingTree(), delayOverride ?? this.effectiveWorkingTreeMs);
-	}
 	coalesceWorkingTrees(paths) {
 		for (const p of paths) {
 			if (this.pendingWorkingTreePaths.size >= maxWorkingTreePaths && !this.pendingWorkingTreePaths.has(p)) {
@@ -244,21 +399,57 @@ var RepositoryWatchSession = class RepositoryWatchSession {
 			}
 			this.pendingWorkingTreePaths.add(p);
 		}
-		this.scheduleWorkingTreeFlush();
+		if (this.hasPendingWorkingTreeChanges) this.workingTreeClock.note();
 	}
-	cancelRepoTimer() {
-		if (this.repoTimer != null) {
-			clearTimeout(this.repoTimer);
-			this.repoTimer = void 0;
-		}
+};
+/** Wraps a session's repo event so each delivery is narrowed to the subscriber's relevant refs (see `subscribe`) */
+function createRelevantRefsEvent(event, relevantRefs) {
+	return (listener, thisArgs, disposables) => event((e) => {
+		const narrowed = narrowToRelevantRefs(e, relevantRefs);
+		if (narrowed != null) listener.call(thisArgs, narrowed);
+	}, void 0, disposables);
+}
+/**
+* Narrows an event to the refs a subscriber cares about. Returns the event itself when no change kind is removed (the
+* kept names then stay a superset, which only makes `mayHaveChangedRef` more conservative), `undefined` when every kind
+* is removed, and otherwise a new event with the kept kinds, names and unnamed kinds.
+*/
+function narrowToRelevantRefs(e, relevantRefs) {
+	let unresolved;
+	for (const change of e.changes) {
+		if (!isRefChangeKind(change) || e.unnamedRefKinds.has(change)) continue;
+		(unresolved ??= /* @__PURE__ */ new Set()).add(change);
 	}
-	cancelWorkingTreeTimer() {
-		if (this.workingTreeTimer != null) {
-			clearTimeout(this.workingTreeTimer);
-			this.workingTreeTimer = void 0;
+	if (unresolved == null) return e;
+	const pseudoRefs = [];
+	for (const name of e.refs) if (!name.startsWith("refs/")) pseudoRefs.push(name);
+	if (pseudoRefs.length !== 0) {
+		unresolved.delete("heads");
+		if (unresolved.size === 0) return e;
+	}
+	const keptNames = new Set(pseudoRefs);
+	for (const ref of relevantRefs()) {
+		const kind = getRefChangeKind(ref);
+		if (kind == null || !e.changes.has(kind)) continue;
+		if (ref === "HEAD") {
+			for (const name of e.refs) if (getRefChangeKind(name) === "heads") keptNames.add(name);
+			unresolved.delete(kind);
+			continue;
 		}
+		const covering = findCoveringRefName(e.refs, ref);
+		if (covering == null) continue;
+		keptNames.add(covering);
+		unresolved.delete(kind);
 	}
-};
+	if (unresolved.size === 0) return e;
+	const keptChanges = [];
+	for (const change of e.changes) if (!isRefChangeKind(change) || !unresolved.has(change)) keptChanges.push(change);
+	if (keptChanges.length === 0) return void 0;
+	return new WatcherRepoChangeEvent(e.repoPath, keptChanges, {
+		names: keptNames,
+		unnamed: e.unnamedRefKinds
+	});
+}
 //#endregion
 export { RepositoryWatchSession };