@volter/editor-core 0.5.57

package/server/editor-sse.ts

@@ -0,0 +1,352 @@
+/**
+ * Shared event fan-out for editor tabs — ONE message vocabulary over TWO
+ * transports.
+ *
+ * A connected editor page is a `EditorEventClient` in this pool, and every
+ * caller (asset browser, Colyseus plugin, the command relay, the tab
+ * bijection) addresses it the same way regardless of how it got here:
+ *
+ *  - `ServerResponse` — the classic `GET /__editor/events` SSE stream. Still
+ *    the transport the share tunnel bridges through (TryCloudflare cannot do
+ *    SSE to the browser, so its gateway consumes this and re-frames it), and
+ *    still curl-debuggable.
+ *  - `EditorSocketClient` — a WebSocket upgrade on that SAME path. Local tabs
+ *    use this one: it carries the identical named events downstream AND the
+ *    tab's control replies upstream, so receipts/results/state no longer
+ *    compete with module loads for the browser's per-origin HTTP connection
+ *    pool. It also answers protocol pings from the browser's network stack
+ *    while the main thread is blocked, which is what lets the relay say
+ *    "busy" instead of guessing "dead".
+ */
+
+import type { ServerResponse } from 'node:http';
+import type { CommandListenerFacts } from './server-utils';
+
+/**
+ * What a tab last told the server about itself (`POST /__editor/state` or the
+ * equivalent control frame).
+ *
+ * It is EVIDENCE FOR A REFUSAL and nothing else now. It used to elect the tab
+ * that owned commands, and that election is what the tab table replaced: who
+ * owns the session is a presence question (`server/tab-presence.ts`), and
+ * answering it from a report the page is not obliged to send is how a live,
+ * blessed tab became unroutable and its commands came back "disconnected".
+ * What survives is the part that was always true — when a command goes
+ * unacknowledged, the refusal can say what that tab was showing and how long
+ * it has been quiet instead of guessing.
+ */
+export interface ClientControlHealth {
+  /** `healthy` means the tab explicitly reported an empty pageErrors list. */
+  readonly errorState: 'healthy' | 'unknown' | 'errored';
+  readonly visible: boolean;
+  readonly focused: boolean;
+  readonly updatedAt: number;
+}
+
+/**
+ * A duplex control socket in the pool.
+ *
+ * Beyond delivery it exposes the two liveness facts an SSE response cannot:
+ * the age of the last protocol pong (answered by the browser's NETWORK stack,
+ * so it stays fresh through a blocked main thread) and a main-thread echo
+ * round trip (answered by the inline bootstrap in index.html, so an
+ * unanswered echo can only mean a blocked main thread).
+ */
+export interface EditorSocketClient {
+  /** Structural discriminator against `ServerResponse`. */
+  readonly kind: 'socket';
+  /** Deliver one framed event; false when the socket can no longer take it. */
+  sendFrame(event: string, data: string, id?: string): boolean;
+  /** True once the socket is closing or closed. */
+  isClosed(): boolean;
+  /** Age in ms of the most recent protocol pong, or null before the first. */
+  lastPongAgeMs(): number | null;
+  /** Round-trip the page's inline main-thread echo responder. */
+  echo(timeoutMs: number): Promise<boolean>;
+  /** End this exact connection because a newer generation superseded it. */
+  close(code: number, reason: string): void;
+}
+
+/** Either transport, as held by the pool and by a pending command's owner. */
+export type EditorEventClient = ServerResponse | EditorSocketClient;
+
+const sseClients = new Set<EditorEventClient>();
+const clientIds = new Map<EditorEventClient, string>();
+const clientParticipantIds = new Map<EditorEventClient, string>();
+const clientControlHealth = new Map<string, ClientControlHealth>();
+/**
+ * Per-page-load command-listener facts (`server-utils.ts`'s
+ * `CommandListenerFacts`), keyed by client id — which IS the page-load id, so
+ * a reload starts from nothing rather than inheriting the dead page's verdict.
+ *
+ * OWNERSHIP: this map is written only by the three `note*` helpers below, and
+ * an entry is dropped only by `dropClient`, exactly where `clientControlHealth`
+ * beside it is dropped — one lifetime, one teardown path, no timer.
+ */
+const clientListenerFacts = new Map<string, MutableCommandListenerFacts>();
+
+interface MutableCommandListenerFacts {
+  attachedAt: number | null;
+  lastRelayAt: number | null;
+  lastReceiptAt: number | null;
+}
+
+function factsFor(clientId: string): MutableCommandListenerFacts {
+  const existing = clientListenerFacts.get(clientId);
+  if (existing) return existing;
+  const fresh: MutableCommandListenerFacts = {
+    attachedAt: null,
+    lastRelayAt: null,
+    lastReceiptAt: null,
+  };
+  clientListenerFacts.set(clientId, fresh);
+  return fresh;
+}
+
+const KEEPALIVE_MS = 15_000;
+let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
+
+/** True for the WebSocket transport. */
+export function isEditorSocketClient(client: EditorEventClient): client is EditorSocketClient {
+  return (client as Partial<EditorSocketClient>).kind === 'socket';
+}
+
+/**
+ * Whether this client's transport can still carry an event.
+ *
+ * Both flags are needed on the SSE side: `writableEnded` reports that the
+ * SERVER called `res.end()`, which nothing does for an SSE response, so a
+ * client abort leaves `writableEnded: false, destroyed: true` (measured).
+ */
+export function isClientAlive(client: EditorEventClient): boolean {
+  if (isEditorSocketClient(client)) return !client.isClosed();
+  return !client.writableEnded && !client.destroyed;
+}
+
+/** End one exact event-stream generation. Its ordinary close handler owns all
+ * table and pending-command cleanup. */
+export function closeClient(client: EditorEventClient, code: number, reason: string): void {
+  if (isEditorSocketClient(client)) {
+    client.close(code, reason);
+    return;
+  }
+  try {
+    client.end();
+  } catch {
+    /* The stream is already ending; its request close still owns cleanup. */
+  }
+}
+
+function dropClient(client: EditorEventClient): void {
+  const clientId = clientIds.get(client);
+  sseClients.delete(client);
+  clientIds.delete(client);
+  clientParticipantIds.delete(client);
+  if (clientId && ![...clientIds.values()].includes(clientId)) {
+    clientControlHealth.delete(clientId);
+    clientListenerFacts.delete(clientId);
+  }
+}
+
+/** Deliver one named event, removing the client from the pool if it is dead. */
+function deliver(client: EditorEventClient, event: string, data: string, id?: string): boolean {
+  try {
+    if (isEditorSocketClient(client)) {
+      if (client.isClosed()) {
+        dropClient(client);
+        return false;
+      }
+      if (!client.sendFrame(event, data, id)) {
+        dropClient(client);
+        return false;
+      }
+      return true;
+    }
+    // `writableEnded` guards against writing to a closed stream.
+    if (client.writableEnded) {
+      dropClient(client);
+      return false;
+    }
+    client.write(`${id === undefined ? '' : `id: ${id}\n`}event: ${event}\ndata: ${data}\n\n`);
+    return true;
+  } catch {
+    // SC3: one dead client must not abort the broadcast loop.
+    dropClient(client);
+    return false;
+  }
+}
+
+/** Start the keepalive ticker once at least one client is connected. */
+function ensureKeepalive(): void {
+  if (keepaliveTimer || sseClients.size === 0) return;
+  keepaliveTimer = setInterval(() => {
+    if (sseClients.size === 0) {
+      stopKeepalive();
+      return;
+    }
+    // Socket clients have the protocol ping instead (editor-control-socket.ts).
+    for (const client of [...sseClients]) {
+      if (isEditorSocketClient(client)) continue;
+      try {
+        if (client.writableEnded) dropClient(client);
+        else client.write(':keepalive\n\n');
+      } catch {
+        dropClient(client);
+      }
+    }
+  }, KEEPALIVE_MS);
+  // Don't keep the process alive solely for the heartbeat.
+  keepaliveTimer.unref?.();
+}
+
+function stopKeepalive(): void {
+  if (keepaliveTimer) {
+    clearInterval(keepaliveTimer);
+    keepaliveTimer = null;
+  }
+}
+
+/** Send an event to all connected editor clients. */
+export function broadcast(event: string, data: unknown): void {
+  const sequence =
+    data &&
+    typeof data === 'object' &&
+    Number.isSafeInteger((data as { sequence?: unknown }).sequence)
+      ? Number((data as { sequence: number }).sequence)
+      : null;
+  const payload = JSON.stringify(data);
+  // Snapshot so deletions during iteration are safe.
+  for (const client of [...sseClients]) {
+    deliver(client, event, payload, sequence === null ? undefined : String(sequence));
+  }
+}
+
+/**
+ * Send an event to the connection(s) carrying one specific clientId
+ * (tab-bijection lifecycle: yield/refocus/close target exactly one tab).
+ * Returns true when at least one live connection received it.
+ */
+export function sendToClient(clientId: string, event: string, data: unknown): boolean {
+  const payload = JSON.stringify(data);
+  let delivered = false;
+  for (const [client, id] of [...clientIds]) {
+    if (id !== clientId) continue;
+    if (deliver(client, event, payload)) delivered = true;
+  }
+  return delivered;
+}
+
+/**
+ * Send an event to the FIRST live connection carrying this clientId, and hand
+ * back the handle it went to.
+ *
+ * The command relay needs the handle, not a boolean: a command is owned by
+ * the connection that took it, so the disconnect settlement can find it
+ * again. `sendToClient` fans out to every connection of a client and can only
+ * answer "did anyone take it", which is the right shape for a lifecycle
+ * notification and the wrong one for a side effect that must happen once.
+ */
+export function sendToClientHandle(
+  clientId: string,
+  event: string,
+  data: unknown,
+): EditorEventClient | null {
+  const payload = JSON.stringify(data);
+  for (const [client, id] of [...clientIds]) {
+    if (id !== clientId) continue;
+    if (deliver(client, event, payload)) return client;
+  }
+  return null;
+}
+
+/**
+ * Send an event to EVERY live connection, optionally scoped to one
+ * participant. Distinct from `broadcast` only in the scoping — session end is
+ * the caller: `tab-close` has to reach the extras and the launcher tabs too,
+ * not just the blessed one, or every other tab falls through to the generic
+ * "Editor disconnected" overlay when the process exits under it.
+ */
+export function sendToAllClients(event: string, data: unknown, participantId?: string): number {
+  const payload = JSON.stringify(data);
+  let delivered = 0;
+  for (const client of [...sseClients]) {
+    if (participantId && clientParticipantIds.get(client) !== participantId) continue;
+    if (deliver(client, event, payload)) delivered++;
+  }
+  return delivered;
+}
+
+/** Add a client connection. Call from the /__editor/events handler. */
+export function addClient(res: EditorEventClient, clientId?: string, participantId?: string): void {
+  sseClients.add(res);
+  if (clientId) clientIds.set(res, clientId);
+  if (participantId) clientParticipantIds.set(res, participantId);
+  ensureKeepalive();
+}
+
+/** Remove a client connection. Call on request/socket close. */
+export function removeClient(res: EditorEventClient): void {
+  dropClient(res);
+  if (sseClients.size === 0) stopKeepalive();
+}
+
+/** Record what a tab last said about itself — read only by a refusal. */
+export function updateClientControlHealth(clientId: string, health: ClientControlHealth): void {
+  clientControlHealth.set(clientId, health);
+}
+
+/** Clear project-specific health snapshots while keeping live sockets. */
+export function clearClientControlHealth(): void {
+  clientControlHealth.clear();
+}
+
+/** The page said its command listener attached (a timestamp) or detached
+ *  (`null`). See `src/editor-api.ts`'s `reportCommandListener`. */
+export function noteCommandListenerAttached(clientId: string, at: number | null): void {
+  factsFor(clientId).attachedAt = at;
+}
+
+/** The relay handed this page a command. */
+export function noteCommandRelay(clientId: string, at: number = Date.now()): void {
+  factsFor(clientId).lastRelayAt = at;
+}
+
+/** This page acknowledged receipt of a relayed command — the OTHER half of the
+ *  verdict, and the one that needs no cooperation beyond the receipt the relay
+ *  already depends on. */
+export function noteCommandReceipt(clientId: string | undefined, at: number = Date.now()): void {
+  if (clientId === undefined) return;
+  factsFor(clientId).lastReceiptAt = at;
+}
+
+/** What is MEASURED about this page-load's command listener. A page-load that
+ *  has never reported anything reads as all-null, which
+ *  `commandListenerHealth` states as `'not attached'` — never as healthy. */
+export function commandListenerFactsFor(clientId: string): CommandListenerFacts {
+  return (
+    clientListenerFacts.get(clientId) ?? {
+      attachedAt: null,
+      lastRelayAt: null,
+      lastReceiptAt: null,
+    }
+  );
+}
+
+/** Number of currently-connected clients (exposed for tests). */
+export function clientCount(participantId?: string): number {
+  if (!participantId) return sseClients.size;
+  return [...clientParticipantIds.values()].filter((candidate) => candidate === participantId)
+    .length;
+}
+
+/** The last health a given tab reported, or `undefined` if it never has. Read
+ *  when a relayed command goes unacknowledged, so the refusal can name what
+ *  that tab was showing and how long it has been silent rather than guessing. */
+export function clientControlHealthFor(clientId: string | null): ClientControlHealth | undefined {
+  return clientId === null ? undefined : clientControlHealth.get(clientId);
+}
+
+/** Client identity for a handle returned by `sendToClientHandle`. */
+export function clientIdForResponse(response: EditorEventClient): string | null {
+  return clientIds.get(response) ?? null;
+}

package/server/engine-provenance.ts

@@ -0,0 +1,169 @@
+/**
+ * What code is this editor session actually serving?
+ *
+ * Measured defect (2026-08-09): a user's editor server came from an engine
+ * checkout parked on a dead feature branch, 162 commits behind `origin/main`.
+ * Three fixes that had already merged were simply absent from the running
+ * editor, and hours went into debugging their absence as live bugs — because
+ * NOTHING in the product reported which commit was being served. The URL, the
+ * project name, the session id and the engine's npm version were all correct
+ * and all useless for that question.
+ *
+ * So the server computes its own checkout's git provenance and reports it
+ * everywhere a human or an agent looks: the `/__editor/project` payload, the
+ * server's own startup banner, `vgai edit`'s ready line, and `vgai status`.
+ *
+ * Two rules this module exists to hold:
+ *
+ * - **Report, never refuse.** A stale checkout still serves. Nothing here
+ *   gates, delays, or fails a boot; every field degrades to `null` on any
+ *   error (no git, not a repo, no `origin/main` ref) and the line still
+ *   prints.
+ * - **Never touch the network.** `behindOriginMain` is measured against the
+ *   LOCAL `origin/main` ref only. A fetch here would make every editor boot
+ *   depend on a remote being reachable, which is exactly the kind of
+ *   always-on dependency a diagnostic must not introduce. The number is
+ *   therefore "behind the last main you fetched", and that is still the
+ *   number that would have caught the 162-commit case.
+ */
+
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export interface EngineProvenance {
+  /** Current branch, or `null` when detached / unknown. */
+  branch: string | null;
+  /** Short HEAD commit, or `null` when unknown. */
+  commit: string | null;
+  /** Commits on the LOCAL `origin/main` ref that HEAD does not have. */
+  behindOriginMain: number | null;
+  /** Tracked-file modifications in the working tree. */
+  dirty: boolean | null;
+}
+
+export const UNKNOWN_ENGINE_PROVENANCE: EngineProvenance = {
+  branch: null,
+  commit: null,
+  behindOriginMain: null,
+  dirty: null,
+};
+
+/**
+ * Runs `git <args>` in the engine checkout. Returns trimmed stdout on success
+ * — `''` is a legitimate success (a clean `git status --porcelain`) and must
+ * stay distinguishable from failure, which is `null`.
+ */
+export type GitRunner = (args: readonly string[]) => Promise<string | null>;
+
+export function createGitRunner(cwd: string): GitRunner {
+  return async (args) => {
+    try {
+      const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: 5_000,
+        maxBuffer: 1024 * 1024,
+      });
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  };
+}
+
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/**
+ * `engineRoot` must BE the repository git discovers, not merely live inside
+ * one. A registry-installed editor sits at `<game>/node_modules/@vgai/editor`,
+ * where `rev-parse --show-toplevel` happily answers with the GAME's repo — and
+ * reporting the game's branch under the word "engine" is worse than reporting
+ * nothing. Mismatch therefore degrades to all-null, the same as no git at all.
+ */
+export async function computeEngineProvenance(
+  engineRoot: string,
+  run: GitRunner,
+): Promise<EngineProvenance> {
+  const toplevel = await run(['rev-parse', '--show-toplevel']);
+  if (toplevel === null || toplevel === '') return UNKNOWN_ENGINE_PROVENANCE;
+  if (canonical(toplevel) !== canonical(engineRoot)) return UNKNOWN_ENGINE_PROVENANCE;
+
+  const [rawBranch, commit, rawBehind, rawStatus] = await Promise.all([
+    run(['rev-parse', '--abbrev-ref', 'HEAD']),
+    run(['rev-parse', '--short', 'HEAD']),
+    run(['rev-list', '--count', 'HEAD..origin/main']),
+    run(['status', '--porcelain', '--untracked-files=no']),
+  ]);
+
+  // Detached HEAD answers the literal string `HEAD`, which would print as
+  // `engine: HEAD @ abc1234`. That is a branch name nobody has.
+  const branch = rawBranch === null || rawBranch === '' || rawBranch === 'HEAD' ? null : rawBranch;
+  const behind = rawBehind === null ? Number.NaN : Number.parseInt(rawBehind, 10);
+
+  return {
+    branch,
+    commit: commit === null || commit === '' ? null : commit,
+    behindOriginMain: Number.isFinite(behind) ? behind : null,
+    dirty: rawStatus === null ? null : rawStatus !== '',
+  };
+}
+
+/**
+ * One provenance read per engine checkout per process. The value is stable for
+ * a server's lifetime: changing engine source restarts the server
+ * (`engine-source-restart.ts`), so there is nothing to invalidate. Keyed by
+ * root rather than module-global so a test — or a process hosting two roots —
+ * cannot poison another's answer.
+ */
+const cache = new Map<string, Promise<EngineProvenance>>();
+
+export function engineProvenance(engineRoot: string, run?: GitRunner): Promise<EngineProvenance> {
+  const key = canonical(engineRoot);
+  const cached = cache.get(key);
+  if (cached) return cached;
+  // Never let a rejection escape into a boot path or an HTTP handler.
+  const pending = computeEngineProvenance(engineRoot, run ?? createGitRunner(key)).catch(
+    () => UNKNOWN_ENGINE_PROVENANCE,
+  );
+  cache.set(key, pending);
+  return pending;
+}
+
+/**
+ * The ONE wording. The server banner, `vgai edit` and `vgai status` all print
+ * this exact string, so a reader comparing two surfaces is never left deciding
+ * whether they disagree or are merely phrased differently.
+ */
+export function formatEngineProvenanceLine(provenance: EngineProvenance | null): string {
+  if (
+    provenance === null ||
+    (provenance.branch === null &&
+      provenance.commit === null &&
+      provenance.behindOriginMain === null &&
+      provenance.dirty === null)
+  ) {
+    return 'engine: provenance unavailable';
+  }
+  const branch = provenance.branch ?? 'detached';
+  const commit = provenance.commit ?? 'unknown commit';
+  const behind =
+    provenance.behindOriginMain === null
+      ? 'distance from origin/main unknown'
+      : `${provenance.behindOriginMain} behind origin/main`;
+  const dirty = provenance.dirty === true ? ' [dirty]' : '';
+  const stale =
+    provenance.behindOriginMain !== null && provenance.behindOriginMain > 0
+      ? ' — STALE: fixes merged to main are not running here'
+      : '';
+  return `engine: ${branch} @ ${commit} (${behind})${dirty}${stale}`;
+}

package/server/engine-source-restart.ts

@@ -0,0 +1,117 @@
+/**
+ * Debounced, content-aware restart gate for the dev host's engine-source
+ * watcher (editor-session diagnosis cause 4). The watcher used to hand ANY
+ * chokidar event straight to the exit-75 restart handoff, which produced
+ * back-to-back restart storms for an actively-editing agent: a multi-file
+ * save burst restarted once per file (each relaunch caught the next event),
+ * and mtime-only touches / git branch switches restoring identical bytes
+ * restarted a process whose imported modules were not actually stale — the
+ * "zombie-tab reload loop". Two minimal suppressions, without changing what
+ * counts as watched:
+ *
+ * - **Content check**: each watched file's content hash is baselined during
+ *   the watcher's initial scan and refreshed as events arrive; an event
+ *   whose bytes match the last-seen hash is ignored entirely (only different
+ *   bytes stale the Node process's imports). Unreadable/deleted paths hash
+ *   to null and are treated as changed, so deletions still restart.
+ * - **Debounce**: a real change (re)arms a short quiet-window timer; the
+ *   restart callback fires ONCE, after the burst goes quiet, reporting the
+ *   burst's FIRST change (matching the old first-event-wins staleSource
+ *   semantics). Once fired, the gate is latched — the process is exiting.
+ *
+ * Hashing and timers are injectable so the decision logic is unit-testable
+ * without filesystem or clock choreography (test-proportionality policy).
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+export interface EngineSourceChange {
+  changedPath: string;
+  changedAt: string;
+}
+
+/** sha256 of a file's bytes, or null when unreadable (deleted, a directory,
+ *  permission). Callers treat null as "changed" — a vanished source file
+ *  stales imports exactly like different bytes do. */
+export function hashFileContent(file: string): string | null {
+  try {
+    return createHash('sha256').update(readFileSync(file)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+export interface EngineSourceRestartGate {
+  /** Record a file's boot-time content during the watcher's initial scan
+   *  (chokidar's pre-`ready` add events) — served content IS boot content,
+   *  since any earlier change already restarted the previous process. */
+  recordBaseline(file: string): void;
+  /** Handle a post-scan watcher event; arms/re-arms the quiet-window timer
+   *  when the file's content actually differs from the last-seen bytes. */
+  handleEvent(event: string, file: string): void;
+  /** Cancel any pending restart (shutdown path). */
+  dispose(): void;
+}
+
+export function createEngineSourceRestartGate(options: {
+  onRestart: (change: EngineSourceChange) => void;
+  /** Quiet window a burst must go silent for before the single restart fires. */
+  quietMs?: number;
+  hashFile?: (file: string) => string | null;
+  /** Timer seam (opaque handle) so tests drive the quiet window directly. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (timer: unknown) => void;
+  now?: () => Date;
+}): EngineSourceRestartGate {
+  const quietMs = options.quietMs ?? 1000;
+  const hashFile = options.hashFile ?? hashFileContent;
+  const setTimer =
+    options.setTimer ?? ((fn: () => void, ms: number): unknown => setTimeout(fn, ms));
+  const clearTimer =
+    options.clearTimer ?? ((timer: unknown) => clearTimeout(timer as NodeJS.Timeout));
+  const now = options.now ?? (() => new Date());
+
+  /** file -> last-seen content hash (baseline scan, then refreshed per event). */
+  const lastSeen = new Map<string, string>();
+  let pending: EngineSourceChange | null = null;
+  let timer: unknown = null;
+  let fired = false;
+
+  const fire = (): void => {
+    timer = null;
+    if (fired || pending === null) return;
+    fired = true;
+    options.onRestart(pending);
+  };
+
+  return {
+    recordBaseline(file: string): void {
+      const hash = hashFile(file);
+      if (hash !== null) lastSeen.set(file, hash);
+    },
+    handleEvent(event: string, file: string): void {
+      if (fired) return;
+      if (event === 'unlink' || event === 'unlinkDir') {
+        // Deletions are always real changes (old any-event behavior kept);
+        // drop the hash so a later re-add with identical bytes still counts
+        // as a change relative to "the file was gone".
+        lastSeen.delete(file);
+      } else {
+        const hash = hashFile(file);
+        if (hash !== null && hash === lastSeen.get(file)) return; // mtime-only touch
+        if (hash !== null) lastSeen.set(file, hash);
+        else lastSeen.delete(file);
+      }
+      if (pending === null) {
+        pending = { changedPath: file, changedAt: now().toISOString() };
+      }
+      if (timer !== null) clearTimer(timer);
+      timer = setTimer(fire, quietMs);
+    },
+    dispose(): void {
+      if (timer !== null) clearTimer(timer);
+      timer = null;
+    },
+  };
+}