@indigoai-us/hq-cloud 6.15.64 → 6.15.66

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, getStateDir, 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,132 @@ 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 FAST_LANE_MAX_FILE_BYTES_ENV = "HQ_SYNC_FAST_LANE_MAX_FILE_BYTES";
+export const DEFAULT_FAST_LANE_MAX_FILES = 32;
+export const DEFAULT_FAST_LANE_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * A per-file ceiling keeps a single medium-sized transfer from consuming the
+ * realtime lane even when the batch aggregate is otherwise below its cap.
+ * 256 KiB comfortably covers ordinary notes and control-plane artifacts while
+ * leaving session logs and other transfer-heavy files in the slow lane.
+ */
+export const DEFAULT_FAST_LANE_MAX_FILE_BYTES = 256 * 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),
+        maxFileBytes: positiveEnvInt(FAST_LANE_MAX_FILE_BYTES_ENV, DEFAULT_FAST_LANE_MAX_FILE_BYTES),
+    };
+}
+/**
+ * Select a bounded realtime prefix from already coalesced work. A path appears
+ * exactly once in this input, so a later change to the same path has already
+ * replaced its earlier revision and cannot straddle lanes.
+ */
+function partitionByKnownSizes(items, sizeOf) {
+    const { maxFiles, maxBytes, maxFileBytes } = resolveFastLaneLimits();
+    const fast = [];
+    const slow = [];
+    let bytes = 0;
+    for (const item of items) {
+        const size = sizeOf(item);
+        if (size === null ||
+            size > maxFileBytes ||
+            fast.length >= maxFiles ||
+            bytes + size > maxBytes) {
+            slow.push(item);
+            continue;
+        }
+        fast.push(item);
+        bytes += size;
+    }
+    return { fast, slow };
+}
+function localPathSize(absolutePath, changes) {
+    // `unlinkDir` has an unbounded journal expansion; never guess its payload.
+    if (changes?.get(absolutePath)?.kind === "unlinkDir")
+        return null;
+    try {
+        const stat = fs.lstatSync(absolutePath);
+        if (stat.isDirectory())
+            return null;
+        return stat.isFile() ? stat.size : 0;
+    }
+    catch (err) {
+        // A missing file is an exact delete and has no content transfer. Any other
+        // stat error leaves its payload unknown and therefore slow.
+        return err.code === "ENOENT" ? 0 : null;
+    }
+}
+/**
+ * Partition one selected watcher batch. The returned batches retain the same
+ * route/filter metadata, but no latest path can appear in both lane maps.
+ */
+export function partitionLocalBatch(batch) {
+    const partition = partitionByKnownSizes([...batch.paths.entries()], ([absolutePath]) => localPathSize(absolutePath, batch.changes));
+    const makeBatch = (entries) => {
+        if (entries.length === 0)
+            return null;
+        const paths = new Map(entries);
+        const changes = new Map();
+        for (const [absolutePath] of entries) {
+            const change = batch.changes?.get(absolutePath);
+            if (change)
+                changes.set(absolutePath, change);
+        }
+        return { ...batch, paths, ...(changes.size > 0 ? { changes } : {}) };
+    };
+    return { fast: makeBatch(partition.fast), slow: makeBatch(partition.slow) };
+}
+/** 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;
+}
+/** A receiver event needs a known small upsert size before it can go realtime. */
+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 +210,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 +350,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.
@@ -285,7 +414,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,
@@ -293,10 +462,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();
             }
         }
@@ -309,9 +492,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) {
@@ -413,51 +611,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;
@@ -542,6 +778,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;
@@ -550,26 +788,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);
@@ -651,18 +891,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 ??=
@@ -730,6 +974,22 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 : relativePath.slice(prefix.length + 1),
         };
     };
+    /**
+     * A receiver event is eligible only when its upsert bytes are known small.
+     * Current publishers do not require a size field, so a locally journaled
+     * version is the backwards-compatible HEAD-size source. An event with no
+     * declared or journal-known size is bulk: guessing would let a large legacy
+     * transfer consume the realtime lane.
+     */
+    const receiverEventSize = (event) => {
+        if (event.kind !== "upsert")
+            return null;
+        const coordinates = journalCoordinates(event.relativePath);
+        if (!coordinates)
+            return null;
+        const size = readJournal(coordinates.slug).files[coordinates.key]?.size;
+        return Number.isSafeInteger(size) && size >= 0 ? size : null;
+    };
     const captureLocalDeleteSnapshots = (relativePath, kind) => {
         const coordinates = journalCoordinates(relativePath);
         const route = routeChangeToTarget(relativePath);
@@ -841,6 +1101,41 @@ 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 publishedContentHashBaseline = () => {
+        const hashes = {};
+        for (const { slug, journal } of listJournals()) {
+            const isPersonal = slug === PERSONAL_VAULT_JOURNAL_SLUG || slug === "personal";
+            const route = isPersonal
+                ? { kind: "personal" }
+                : { kind: "company", slug };
+            if (!isWatchRouteSelected(route, watchRouteSelection))
+                continue;
+            for (const [key, entry] of Object.entries(journal.files)) {
+                // Tombstones and link records have no live regular-file body for the
+                // PushEventEmitter's SHA-256 comparison, so they must not seed it.
+                if (entry.removedAt !== undefined ||
+                    entry.kind === "symlink" ||
+                    entry.localDiverges)
+                    continue;
+                hashes[isPersonal ? key : `companies/${slug}/${key}`] = `sha256:${entry.hash}`;
+            }
+        }
+        return hashes;
+    };
     const prepareWatcherChanges = (changes) => {
         const journals = new Map();
         const dirty = new Set();
@@ -939,7 +1234,7 @@ 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" &&
@@ -953,9 +1248,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"
                             ? []
@@ -980,11 +1278,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();
                 }
             }
         }
@@ -1012,7 +1314,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;
             }
@@ -1146,6 +1448,36 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             watcher.onChange((changedRelPath, batch) => {
                 if (stopped)
                     return;
+                // Peel a bounded realtime sub-batch from a mixed watcher batch while a
+                // bulk pass is in flight. The residue enters the ordinary pending drain
+                // immediately; a latest path appears in exactly one of these maps.
+                const selectedBatch = batch ? selectWatchBatch(batch) : null;
+                const lanes = selectedBatch && !selectedBatch.overflowed
+                    ? partitionLocalBatch(selectedBatch)
+                    : null;
+                if (lanes?.fast &&
+                    activeSlowPass !== null) {
+                    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(lanes.fast, generation, true).then((exit) => {
+                        if (exit === 0)
+                            return;
+                        restorePendingWatcherPaths(lanes.fast.paths, generation);
+                        interruptWait();
+                    }).catch((err) => {
+                        restorePendingWatcherPaths(lanes.fast.paths, generation);
+                        process.stderr.write(`watch fast-lane scoped push failed, will retry next tick: ${describeError(err)}\n`);
+                        interruptWait();
+                    });
+                    if (lanes.slow && addPendingWatcherChange(undefined, lanes.slow)) {
+                        realtimeState.scheduler?.signal("watcher");
+                        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
@@ -1178,6 +1510,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);
@@ -1214,25 +1570,39 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
             // so it cannot overlap the pass that may currently own the operation
             // lock.
             interruptWait();
-            const pathsByRoute = new Map();
-            for (const event of events) {
-                const route = routeChangeToTarget(event.relativePath);
-                if (!route)
-                    continue;
-                const key = routeKey(route);
-                const group = pathsByRoute.get(key) ?? { route, paths: [] };
-                group.paths.push(event.relativePath);
-                pathsByRoute.set(key, group);
-            }
-            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);
-                if (passExitCode(result) !== 0) {
-                    throw new Error(`targeted pull failed with exit code ${passExitCode(result)}`);
+            // Apply the caps once across the whole delivery, then retain the residue
+            // in the normal lane. The receiver already coalesces to one latest event
+            // per path, so the partition cannot split revisions of one path.
+            const lanes = partitionByKnownSizes(events, receiverEventSize);
+            const drainLane = async (lane, laneEvents) => {
+                const pathsByRoute = new Map();
+                for (const event of laneEvents) {
+                    const route = routeChangeToTarget(event.relativePath);
+                    if (!route)
+                        continue;
+                    const key = routeKey(route);
+                    const group = pathsByRoute.get(key) ?? { route, paths: [] };
+                    group.paths.push(event.relativePath);
+                    pathsByRoute.set(key, group);
                 }
-            }
+                for (const { route, paths } of pathsByRoute.values()) {
+                    const targetedArgv = buildTargetedPullArgv(route, passArgv, paths);
+                    const result = await runGuarded(targetedArgv, undefined, lane);
+                    if (passExitCode(result) !== 0) {
+                        throw new Error(`targeted pull failed with exit code ${passExitCode(result)}`);
+                    }
+                }
+            };
+            // Dispatch realtime work before awaiting its bulk residue. This lets an
+            // established slow pass continue while the small scoped pull uses its
+            // ref-counted lock carve-out; the residue remains serialized and cannot
+            // starve the slow lane.
+            await drainLane("fast", lanes.fast);
+            await drainLane("slow", lanes.slow);
+        };
+        receiverSyncBatchFn.partition = (events) => {
+            const lanes = partitionByKnownSizes(events, receiverEventSize);
+            return [lanes.fast, lanes.slow].filter((lane) => lane.length > 0);
         };
         const createReceiver = deps.createReceiver ?? (() => new NoopPushReceiver());
         receiver = createReceiver({ syncBatchFn: receiverSyncBatchFn, hqRoot });
@@ -1246,10 +1616,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)}`);
                     }
@@ -1297,6 +1680,8 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                     log: (m) => process.stderr.write(`${m}\n`),
                     telemetryClient: eventSyncClient,
                     telemetryClaims: claims,
+                    publishedContentHashStateDir: getStateDir(),
+                    initialPublishedContentHashes: publishedContentHashBaseline(),
                 });
                 if (!handles)
                     return;
@@ -1391,6 +1776,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
@@ -1402,6 +1789,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)
@@ -1412,6 +1801,7 @@ export async function runWatchLoop(argv, parsed, deps, runtime) {
                 bareWake ||
                 batchOverLimit ||
                 overflowRoutesUnknown ||
+                watcherWarmupCatchupFailed ||
                 scheduledInterval;
             const emitDecision = (mode, decisionReasons) => {
                 emitFullReconcileDecision({
@@ -1447,7 +1837,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