@indigoai-us/hq-cloud 6.15.63 → 6.15.65

package/dist/bin/sync-runner-watch-loop.js

@@ -12,7 +12,7 @@ import { PARTIAL_SYNC_EXIT } from "../lib/exit-codes.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import { localPathForVaultKey } from "../local-path-codec.js";
 import { TreeWatcher, resolveEventDebounceConfig, systemClock, } from "../watcher.js";
-import { clearLocalDeleteIntent, markLocalDeleteIntent, PERSONAL_VAULT_JOURNAL_SLUG, openJournalStoreSession, readJournal, writeJournal, } from "../journal.js";
+import { clearLocalDeleteIntent, markLocalDeleteIntent, PERSONAL_VAULT_JOURNAL_SLUG, openJournalStoreSession, listJournals, readJournal, writeJournal, } from "../journal.js";
 import { NoopPushReceiver, } from "../sync/push-receiver.js";
 import { resolveEventSync, startEventSync as defaultStartEventSync, } from "../sync/event-sync.js";
 import { buildRoutePullArgv, buildScopedPushArgv, buildScopedDrainPullArgv, buildTargetedPullArgv, isWatchRouteSelected, routeChangeToTarget, routeKey, } from "./sync-runner-watch-routes.js";
@@ -44,6 +44,63 @@ function emitFullReconcileDecision({ mode, reasons, triggers, pollTick, configur
  */
 export const DEFAULT_EVENT_BATCH_LIMIT = 10_000;
 export const EVENT_BATCH_LIMIT_ENV = "HQ_SYNC_EVENT_BATCH_LIMIT";
+/**
+ * Fast-lane admission is deliberately conservative: a normal editor save is
+ * a handful of files and well below 4 MiB, whereas session-log catch-up is
+ * neither.  Operators may tune both limits without changing scheduling
+ * semantics.  Invalid values retain the safe defaults.
+ */
+export const FAST_LANE_MAX_FILES_ENV = "HQ_SYNC_FAST_LANE_MAX_FILES";
+export const FAST_LANE_MAX_BYTES_ENV = "HQ_SYNC_FAST_LANE_MAX_BYTES";
+export const DEFAULT_FAST_LANE_MAX_FILES = 32;
+export const DEFAULT_FAST_LANE_MAX_BYTES = 4 * 1024 * 1024;
+function positiveEnvInt(name, fallback) {
+    const value = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export function resolveFastLaneLimits() {
+    return {
+        maxFiles: positiveEnvInt(FAST_LANE_MAX_FILES_ENV, DEFAULT_FAST_LANE_MAX_FILES),
+        maxBytes: positiveEnvInt(FAST_LANE_MAX_BYTES_ENV, DEFAULT_FAST_LANE_MAX_BYTES),
+    };
+}
+/** A missing/stat-failed path is never allowed to bypass the slow lane. */
+export function isFastLocalBatch(paths, changes) {
+    const { maxFiles, maxBytes } = resolveFastLaneLimits();
+    let files = 0;
+    let bytes = 0;
+    for (const absolutePath of paths) {
+        files += 1;
+        if (files > maxFiles)
+            return false;
+        // `unlinkDir` arrives after its path is gone. Its scoped push expands the
+        // journal subtree through deleteScopeRoots, so its payload cannot be
+        // bounded by the absent directory's lstat result.
+        if (changes?.get(absolutePath)?.kind === "unlinkDir")
+            return false;
+        try {
+            const stat = fs.lstatSync(absolutePath);
+            // A directory-scoped operation may expand to an arbitrary payload. Do
+            // not guess: it belongs in the slow lane.
+            if (stat.isDirectory())
+                return false;
+            bytes += stat.isFile() ? stat.size : 0;
+        }
+        catch (err) {
+            // Deletes are zero-byte operations; every other stat failure is unknown
+            // payload and must retain normal serialization.
+            if (err.code !== "ENOENT")
+                return false;
+        }
+        if (bytes > maxBytes)
+            return false;
+    }
+    return files > 0;
+}
+/** Receiver events carry no content length, so only bounded event batches qualify. */
+export function isFastReceiverBatch(eventCount) {
+    return eventCount > 0 && eventCount <= resolveFastLaneLimits().maxFiles;
+}
 export function resolveEventBatchLimit(env = process.env) {
     const raw = env[EVENT_BATCH_LIMIT_ENV];
     if (raw === undefined || raw.trim() === "")
@@ -84,6 +141,8 @@ export function resolveFullReconcileMs(env = process.env) {
 const ADAPTIVE_POLL_FLOOR_MS = 60_000;
 const ADAPTIVE_POLL_CEIL_MS = 600_000;
 const WATCH_IDLE_HEARTBEAT_INTERVAL_MS = 30_000;
+/** Covers coarse timestamp filesystems and scheduling just before watcher start. */
+const WATCHER_WARMUP_SAFETY_MARGIN_MS = 2_000;
 /** Initial poll-only recovery delay after a watcher conclusively stands down. */
 export const WATCHER_REDISCOVERY_RETRY_MS = 5 * 60_000;
 /** Ceiling for exponential retry delays after consecutive watcher stand-downs. */
@@ -222,6 +281,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             skipPersonalEnv === "yes",
     };
     const hqRoot = parsed.hqRoot;
+    const serviceStartedAt = Date.now();
     // Delayed and daily: this must never be attached to the 15s poll cadence.
     // Stage 0 remains dry-run only; the standalone hq-backup-prune command is
     // the explicitly-gated apply surface.
@@ -260,8 +320,14 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     // mis-defaults an omitted --direction to "both" and picks the wrong
     // occurrence on duplicates). Fall back to the parser's own default ("pull").
     const originalDirection = parsed.direction ?? "pull";
-    const drainRunsPush = originalDirection === "both" || originalDirection === "push";
     const drainRunsPull = originalDirection === "both" || originalDirection === "pull";
+    // `--event-push` is an explicit local-write delivery contract.  The
+    // one-shot/cadence direction still controls ordinary reconciliation, but a
+    // watcher batch must always take its bounded scoped push path even when the
+    // parser's legacy default direction is pull. Otherwise the drain snapshots
+    // and clears a local batch while running only its pull leg, leaving the
+    // write for a later full reconcile.
+    const watcherDrainRunsPush = eventPush;
     if (parsed.lockTimeoutSec === 0) {
         try {
             const handle = acquireOperationLock(hqRoot, "sync", {
@@ -279,7 +345,47 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             throw err;
         }
     }
-    const runPassWithLock = async (passArgvForRun, prepare) => {
+    // `activeSlowPass` is assigned before its task has necessarily acquired the
+    // cross-process lock (it may be waiting behind a rescue or a second runner).
+    // Fast work may bypass the lock only while this process *actually owns* it;
+    // otherwise it must participate in normal lock acquisition.
+    let processOwnsOperationLock = false;
+    let operationLockUsers = 0;
+    let resolveNoOperationLockUsers = null;
+    const acquireOperationLockUser = () => {
+        operationLockUsers += 1;
+    };
+    const releaseOperationLockUser = () => {
+        operationLockUsers -= 1;
+        if (operationLockUsers !== 0)
+            return;
+        const resolve = resolveNoOperationLockUsers;
+        resolveNoOperationLockUsers = null;
+        resolve?.();
+    };
+    const waitForOperationLockUsers = () => {
+        if (operationLockUsers === 0)
+            return null;
+        return new Promise((resolve) => {
+            resolveNoOperationLockUsers = resolve;
+        });
+    };
+    const runPassWithLock = async (passArgvForRun, prepare, lane = "slow") => {
+        // The operation lock remains the cross-process sync/rescue exclusion
+        // boundary. A fast scoped pass is the one deliberate in-process exception:
+        // its keyed journal delta and per-object mutation are independent from the
+        // slow pass's bulk paths, and the slow pass already owns the root lock.
+        // Never bypass the lock when no slow pass is active.
+        if (lane === "fast" && processOwnsOperationLock) {
+            acquireOperationLockUser();
+            try {
+                prepare?.();
+                return await runPass(passArgvForRun);
+            }
+            finally {
+                releaseOperationLockUser();
+            }
+        }
         try {
             const handle = acquireOperationLock(hqRoot, "sync", {
                 timeoutSec: 0,
@@ -287,10 +393,24 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 deferToWaiters: true,
             });
             try {
+                if (lane === "slow") {
+                    processOwnsOperationLock = true;
+                    acquireOperationLockUser();
+                }
                 prepare?.();
                 return await runPass(passArgvForRun);
             }
             finally {
+                if (lane === "slow") {
+                    releaseOperationLockUser();
+                    // The root lock protects a fast pass that was admitted while this
+                    // slow pass owned it. Do not make it acquirable by rescue/another
+                    // runner until every such in-process user has completed.
+                    const remainingUsers = waitForOperationLockUsers();
+                    if (remainingUsers)
+                        await remainingUsers;
+                    processOwnsOperationLock = false;
+                }
                 handle.release();
             }
         }
@@ -303,9 +423,24 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             }
         }
         try {
-            return await withOperationLock(hqRoot, "sync", () => {
-                prepare?.();
-                return runPass(passArgvForRun);
+            return await withOperationLock(hqRoot, "sync", async () => {
+                if (lane === "slow") {
+                    processOwnsOperationLock = true;
+                    acquireOperationLockUser();
+                }
+                try {
+                    prepare?.();
+                    return await runPass(passArgvForRun);
+                }
+                finally {
+                    if (lane === "slow") {
+                        releaseOperationLockUser();
+                        const remainingUsers = waitForOperationLockUsers();
+                        if (remainingUsers)
+                            await remainingUsers;
+                        processOwnsOperationLock = false;
+                    }
+                }
             }, { timeoutSec: parsed.lockTimeoutSec, deferToWaiters: true });
         }
         catch (err) {
@@ -407,51 +542,89 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             observedInterruptGeneration = interruptGeneration;
         }
     };
-    let activePass = null;
-    const pendingPasses = [];
+    let activeSlowPass = null;
+    let activeFastPass = null;
+    const pendingSlowPasses = [];
+    const pendingFastPasses = [];
     const resolveStoppedQueue = () => {
-        while (pendingPasses.length > 0) {
-            pendingPasses.shift()?.resolve(0);
+        for (const queue of [pendingFastPasses, pendingSlowPasses]) {
+            while (queue.length > 0)
+                queue.shift()?.resolve(0);
         }
     };
     const drainQueuedPasses = () => {
-        if (activePass !== null)
-            return;
         if (stopped) {
             resolveStoppedQueue();
             return;
         }
-        const next = pendingPasses.shift();
-        if (!next)
-            return;
-        const current = startGuardedTask(next.task);
-        void current.then(next.resolve, next.reject);
+        if (activeFastPass === null) {
+            const fast = pendingFastPasses.shift();
+            if (fast) {
+                const current = startGuardedTask(fast.task, "fast");
+                void current.then(fast.resolve, fast.reject);
+            }
+        }
+        // A fast pass that acquired the operation lock normally (rather than
+        // bypassing an in-process slow holder) still owns the cross-process
+        // boundary. Slow work must queue behind it; only fast work is allowed to
+        // overlap an already-lock-owning slow pass.
+        if (activeSlowPass === null && activeFastPass === null) {
+            const slow = pendingSlowPasses.shift();
+            if (slow) {
+                const current = startGuardedTask(slow.task, "slow");
+                void current.then(slow.resolve, slow.reject);
+            }
+        }
     };
-    const startGuardedTask = (task) => {
-        const current = stopped
-            ? Promise.resolve(0)
-            : task();
-        activePass = current;
+    const startGuardedTask = (task, lane) => {
+        // Claim the lane before invoking `task`: a task can synchronously activate
+        // a watcher/scheduler callback before returning its promise. Without this
+        // placeholder that re-entrant callback sees an idle lane and starts a
+        // second lock contender.
+        const placeholder = Promise.resolve(0);
+        if (lane === "fast")
+            activeFastPass = placeholder;
+        else
+            activeSlowPass = placeholder;
+        let current;
+        try {
+            current = stopped ? placeholder : task();
+        }
+        catch (err) {
+            current = Promise.reject(err);
+        }
+        if (lane === "fast")
+            activeFastPass = current;
+        else
+            activeSlowPass = current;
         void current
             .finally(() => {
-            if (activePass === current) {
-                activePass = null;
+            if (lane === "fast" && activeFastPass === current) {
+                activeFastPass = null;
+                drainQueuedPasses();
+            }
+            else if (lane === "slow" && activeSlowPass === current) {
+                activeSlowPass = null;
                 drainQueuedPasses();
             }
         })
             .catch(() => undefined);
         return current;
     };
-    const runGuardedTask = (task) => {
-        if (activePass === null && pendingPasses.length === 0) {
-            return startGuardedTask(task);
+    const runGuardedTask = (task, lane = "slow") => {
+        const active = lane === "fast"
+            ? activeFastPass
+            : activeSlowPass ?? activeFastPass;
+        const queued = lane === "fast" ? pendingFastPasses : pendingSlowPasses;
+        if (active === null && queued.length === 0) {
+            return startGuardedTask(task, lane);
         }
         return new Promise((resolve, reject) => {
-            pendingPasses.push({ task, resolve, reject });
+            queued.push({ task, lane, resolve, reject });
             drainQueuedPasses();
         });
     };
-    const runGuarded = (passArgvForRun, prepare) => runGuardedTask(() => runPassWithLock(passArgvForRun, prepare));
+    const runGuarded = (passArgvForRun, prepare, lane = "slow") => runGuardedTask(() => runPassWithLock(passArgvForRun, prepare, lane), lane);
     let watcher = null;
     let eventPushSurfacesActivated = false;
     let watcherUnavailableWarned = false;
@@ -536,6 +709,8 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     let pendingWatcherBatchGeneration = null;
     const lastPublishedWatcherBatchGenerationByRoute = new Map();
     let pendingWatcherBareChange = false;
+    let pendingWatcherWarmupCatchup = false;
+    let pendingWatcherWarmupCatchupFailed = false;
     let pendingWatcherOverflowed = false;
     let pendingWatcherDroppedPaths = 0;
     let pendingWatcherDroppedBytes = 0;
@@ -544,26 +719,28 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
     // pending state carried them; one hint-less overflow poisons the union.
     const pendingWatcherDroppedRouteHints = new Set();
     let pendingWatcherDroppedRoutesUnknown = false;
+    const selectWatchBatch = (batch) => {
+        const paths = new Map();
+        const changes = new Map();
+        for (const [absolutePath, relativePath] of batch.paths.entries()) {
+            const route = routeChangeToTarget(relativePath);
+            if (!route || !isWatchRouteSelected(route, watchRouteSelection))
+                continue;
+            paths.set(absolutePath, relativePath);
+            const change = batch.changes?.get(absolutePath);
+            if (change)
+                changes.set(absolutePath, change);
+        }
+        if (paths.size === 0)
+            return null;
+        return { ...batch, paths, changes };
+    };
     const addPendingWatcherChange = (changedRelPath, batch) => {
         if (batch) {
-            const paths = new Map();
-            const changes = new Map();
-            for (const [absolutePath, relativePath] of batch.paths.entries()) {
-                const route = routeChangeToTarget(relativePath);
-                if (!route || !isWatchRouteSelected(route, watchRouteSelection))
-                    continue;
-                paths.set(absolutePath, relativePath);
-                const change = batch.changes?.get(absolutePath);
-                if (change)
-                    changes.set(absolutePath, change);
-            }
-            if (paths.size === 0)
+            const selectedBatch = selectWatchBatch(batch);
+            if (!selectedBatch)
                 return false;
-            batch = {
-                ...batch,
-                paths,
-                changes,
-            };
+            batch = selectedBatch;
         }
         else if (changedRelPath) {
             const route = routeChangeToTarget(changedRelPath);
@@ -645,18 +822,22 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 }
                 : null;
         const bare = pendingWatcherBareChange;
+        const warmupCatchup = pendingWatcherWarmupCatchup;
+        const warmupCatchupFailed = pendingWatcherWarmupCatchupFailed;
         const generation = pendingWatcherBatchGeneration;
         pendingWatcherPaths.clear();
         pendingWatcherChanges.clear();
         pendingWatcherOriginalBatch = null;
         pendingWatcherBareChange = false;
+        pendingWatcherWarmupCatchup = false;
+        pendingWatcherWarmupCatchupFailed = false;
         pendingWatcherOverflowed = false;
         pendingWatcherDroppedPaths = 0;
         pendingWatcherDroppedBytes = 0;
         pendingWatcherDroppedRouteHints.clear();
         pendingWatcherDroppedRoutesUnknown = false;
         pendingWatcherBatchGeneration = null;
-        return { batch, bare, generation };
+        return { batch, bare, warmupCatchup, warmupCatchupFailed, generation };
     };
     const restorePendingWatcherPaths = (paths, generation) => {
         pendingWatcherBatchGeneration ??=
@@ -835,6 +1016,20 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         }
         return snapshots;
     };
+    const warmupJournalPaths = () => {
+        const paths = [];
+        for (const { slug, journal } of listJournals()) {
+            const route = slug === PERSONAL_VAULT_JOURNAL_SLUG || slug === "personal"
+                ? { kind: "personal" }
+                : { kind: "company", slug };
+            if (!isWatchRouteSelected(route, watchRouteSelection))
+                continue;
+            for (const key of Object.keys(journal.files)) {
+                paths.push(route.kind === "personal" ? key : `companies/${route.slug}/${key}`);
+            }
+        }
+        return paths;
+    };
     const prepareWatcherChanges = (changes) => {
         const journals = new Map();
         const dirty = new Set();
@@ -933,12 +1128,12 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
         }
         return false;
     };
-    const runScopedDrain = async (batch, watcherBatchGeneration) => {
+    const runScopedDrain = async (batch, watcherBatchGeneration, wakeOnPushFailure = false) => {
         const grouped = batch && batch.paths.size > 0 ? groupBatchByRoute(batch) : null;
         const skipCompanies = grouped ? resolveSkipCompanies() : null;
         const isPausedRoute = (route) => route.kind === "company" &&
             (skipCompanies?.has(route.slug.toLowerCase()) ?? false);
-        if (drainRunsPush && grouped) {
+        if (watcherDrainRunsPush && grouped) {
             for (const group of grouped.values()) {
                 // Paused workspaces: drop the scoped push without uploading or
                 // publishing event-sync metadata (path/hash must not leak while Off).
@@ -947,9 +1142,12 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 }
                 const scopedArgv = buildScopedPushArgv(group.route, group.relPaths, passArgv, group.deleteScopeRoots);
                 try {
+                    const lane = isFastLocalBatch(group.paths.keys(), group.changes)
+                        ? "fast"
+                        : "slow";
                     const result = await runGuarded(scopedArgv, group.changes.size > 0
                         ? () => prepareWatcherChanges(group.changes)
-                        : undefined);
+                        : undefined, lane);
                     if (passExitCode(result) === 0) {
                         const refusedPaths = new Set(typeof result === "number"
                             ? []
@@ -974,11 +1172,15 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                     }
                     else {
                         restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
+                        if (wakeOnPushFailure)
+                            interruptWait();
                     }
                 }
                 catch (err) {
                     restorePendingWatcherPaths(group.paths, watcherBatchGeneration);
                     process.stderr.write(`watch scoped push failed, will retry next tick: ${describeError(err)}\n`);
+                    if (wakeOnPushFailure)
+                        interruptWait();
                 }
             }
         }
@@ -1006,7 +1208,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                         continue;
                     ranPersonalDrain = true;
                 }
-                const exit = passExitCode(await runGuarded(pullArgv));
+                const exit = passExitCode(await runGuarded(pullArgv, undefined, isFastLocalBatch(group.paths.keys(), group.changes) ? "fast" : "slow"));
                 if (exit !== 0 && worstExit === 0)
                     worstExit = exit;
             }
@@ -1048,7 +1250,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 skipCompanies.has(route.slug.toLowerCase())) {
                 continue;
             }
-            if (drainRunsPush) {
+            if (watcherDrainRunsPush) {
                 // Whole-route push (no --scope-path): the dropped paths are unknown,
                 // so the route's full walk is the narrowest sound scope.
                 const exit = passExitCode(await runGuarded(buildScopedPushArgv(route, [], passArgv)));
@@ -1140,6 +1342,31 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             watcher.onChange((changedRelPath, batch) => {
                 if (stopped)
                     return;
+                // A complete, small watcher batch is dispatched immediately while a
+                // bulk pass is in flight. Leaving it in the next poll iteration would
+                // still make it wait for that pass even though the fast lane exists.
+                const selectedBatch = batch ? selectWatchBatch(batch) : null;
+                if (selectedBatch &&
+                    !selectedBatch.overflowed &&
+                    activeSlowPass !== null &&
+                    isFastLocalBatch(selectedBatch.paths.keys(), selectedBatch.changes)) {
+                    const generation = ++nextWatcherBatchGeneration;
+                    // Fast dispatch bypasses the pending-batch ingress, so preserve both
+                    // of its contracts here: only selected routes may run, and V2 sees
+                    // the same dirty signal as the compatibility drain.
+                    realtimeState.scheduler?.signal("watcher");
+                    void runScopedDrain(selectedBatch, generation, true).then((exit) => {
+                        if (exit === 0)
+                            return;
+                        restorePendingWatcherPaths(selectedBatch.paths, generation);
+                        interruptWait();
+                    }).catch((err) => {
+                        restorePendingWatcherPaths(selectedBatch.paths, generation);
+                        process.stderr.write(`watch fast-lane scoped push failed, will retry next tick: ${describeError(err)}\n`);
+                        interruptWait();
+                    });
+                    return;
+                }
                 if (addPendingWatcherChange(changedRelPath, batch)) {
                     // The V1 watcher batch keeps its existing compatibility behavior. A
                     // V2-enrolled scope observes the same dirty hint through its own
@@ -1172,6 +1399,30 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 // initial walk will finish.
                 watcherRediscoveryRetries = 0;
                 process.stderr.write(`hq-sync-runner: event-push watcher active (watched-paths=${watchedPaths ?? "unknown"})\n`);
+                const startedAt = Date.now();
+                try {
+                    const catchup = watcher.collectWarmupCatchup?.(serviceStartedAt - WATCHER_WARMUP_SAFETY_MARGIN_MS, warmupJournalPaths());
+                    if (!catchup)
+                        return;
+                    const queued = addPendingWatcherChange(undefined, catchup.batch);
+                    pendingWatcherWarmupCatchup ||= queued;
+                    process.stderr.write(JSON.stringify({
+                        type: "watcher-warmup-catchup",
+                        reason: "watch-set-ready",
+                        pathsFound: catchup.batch.paths.size,
+                        scannedPaths: catchup.scannedPaths,
+                        elapsedMs: Date.now() - startedAt,
+                        queued,
+                    }) + "\n");
+                    if (queued)
+                        interruptWait();
+                }
+                catch (err) {
+                    process.stderr.write(`hq-sync-runner: watcher warm-up catch-up failed: ${describeError(err)}\n`);
+                    // A scan failure must not silently extend the warm-up blind spot.
+                    pendingWatcherWarmupCatchupFailed = true;
+                    interruptWait();
+                }
             };
             if (watcher.onReady)
                 watcher.onReady(reportWatcherReady);
@@ -1209,20 +1460,27 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             // lock.
             interruptWait();
             const pathsByRoute = new Map();
+            let eligibleEventCount = 0;
             for (const event of events) {
                 const route = routeChangeToTarget(event.relativePath);
                 if (!route)
                     continue;
+                eligibleEventCount += 1;
                 const key = routeKey(route);
                 const group = pathsByRoute.get(key) ?? { route, paths: [] };
                 group.paths.push(event.relativePath);
                 pathsByRoute.set(key, group);
             }
+            // One receiver delivery can fan out to many routes. Apply the advertised
+            // cap to its whole eligible payload, not independently to each route.
+            const lane = isFastReceiverBatch(eligibleEventCount)
+                ? "fast"
+                : "slow";
             for (const { route, paths } of pathsByRoute.values()) {
                 // One guarded targeted pass per affected route, with every coalesced
                 // path for that route expressed through the watcher's existing argv seam.
                 const targetedArgv = buildTargetedPullArgv(route, passArgv, paths);
-                const result = await runGuarded(targetedArgv);
+                const result = await runGuarded(targetedArgv, undefined, lane);
                 if (passExitCode(result) !== 0) {
                     throw new Error(`targeted pull failed with exit code ${passExitCode(result)}`);
                 }
@@ -1240,10 +1498,23 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             void deps.startRealtimeScheduler({
                 hqRoot,
                 runGuarded: async (drain) => {
-                    const outcome = await runGuardedTask(() => runTaskWithLock(async () => {
-                        await drain();
-                        return 0;
-                    }));
+                    let outcome;
+                    try {
+                        outcome = await runGuardedTask(() => runTaskWithLock(async () => {
+                            await drain();
+                            return 0;
+                        }));
+                    }
+                    catch (err) {
+                        // Scheduler clients may have already been disposed when a queued
+                        // drain finally reaches the lock. Surface the late failure, but do
+                        // not leak an unhandled rejection after shutdown has completed.
+                        if (stopped) {
+                            process.stderr.write("realtime scheduler: cancelled drain failed after shutdown\n");
+                            return;
+                        }
+                        throw err;
+                    }
                     if (passExitCode(outcome) !== 0) {
                         throw new Error(`realtime scheduler drain exited ${passExitCode(outcome)}`);
                     }
@@ -1385,6 +1656,8 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             const eventPushSurfacesInactive = eventPush && !eventPushSurfacesActivated;
             const firstTick = pollTick === 1;
             const bareWake = pending.bare;
+            const watcherWarmupCatchup = pending.warmupCatchup;
+            const watcherWarmupCatchupFailed = pending.warmupCatchupFailed;
             const overflowRoutesUnknown = pending.batch?.overflowed === true && !overflowWithKnownRoutes;
             const scheduledInterval = fullReconcileIntervalMs === undefined
                 ? pollTick % FULL_RECONCILE_EVERY_TICKS === 0
@@ -1396,6 +1669,8 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 "bare-wake": bareWake,
                 "batch-over-limit": batchOverLimit,
                 "overflow-routes-unknown": overflowRoutesUnknown,
+                "watcher-warmup-catch-up": watcherWarmupCatchup,
+                "watcher-warmup-catch-up-failed": watcherWarmupCatchupFailed,
                 "scheduled-interval": scheduledInterval,
             };
             const reasons = Object.entries(triggers)
@@ -1406,6 +1681,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 bareWake ||
                 batchOverLimit ||
                 overflowRoutesUnknown ||
+                watcherWarmupCatchupFailed ||
                 scheduledInterval;
             const emitDecision = (mode, decisionReasons) => {
                 emitFullReconcileDecision({
@@ -1441,7 +1717,11 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                     // were dropped); ordinary batches remain path-scoped. Label those
                     // distinct scopes so operators can distinguish them from a full
                     // all-vault reconcile.
-                    emitDecision(overflowWithKnownRoutes ? "route" : "scoped", reasons);
+                    emitDecision(watcherWarmupCatchup
+                        ? "catch-up"
+                        : overflowWithKnownRoutes
+                            ? "route"
+                            : "scoped", reasons);
                 }
                 catch (err) {
                     // Never silently drop a change: any failure inside the targeted