@indigoai-us/hq-cloud 6.18.52 → 6.18.54

package/dist/bin/sync-runner.js

@@ -21,6 +21,7 @@
  *                             fanout. Combined with HQ_SYNC_SKIP_PERSONAL env
  *                             (either truthy disables personal sync). No-op
  *                             outside --companies mode.
+ *   --qmd-full-refresh        Bypass the post-sync QMD minimum interval.
  *   --json                    Ignored — ndjson on stdout is the default and
  *                             only output mode. Accepted for symmetry with the
  *                             AppBar's argv in case someone passes it.
@@ -68,6 +69,7 @@
 import * as os from "os";
 import * as path from "path";
 import * as fs from "fs";
+import { localPathForVaultKey } from "../local-path-codec.js";
 import { randomUUID } from "node:crypto";
 import { monitorEventLoopDelay, performance } from "node:perf_hooks";
 import { fileURLToPath } from "url";
@@ -79,6 +81,7 @@ import { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, computePersonalVaultPaths, } from ".
 import { sync as defaultSync } from "../cli/sync.js";
 import { releaseHeldOperationLocks, suppressOperationLockSignalReraise, } from "../operation-lock.js";
 import { share as defaultShare } from "../cli/share.js";
+import { WatcherCatchupSkipStore, watcherCatchupSkipStorePath, } from "./watcher-catchup-skip-store.js";
 import { ensureCompanyVaultTransport } from "../company-vault-transport.js";
 import { HQ_CLOUD_VERSION } from "../version.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
@@ -87,6 +90,7 @@ import { collectAndSendOutcomeTelemetry, OUTCOME_STORY_DONE_STATE_FLAG, } from "
 import { resolveOntologyEntityPush } from "../lib/ontology-entity-push.js";
 import { emitCloudTelemetry } from "../telemetry-events.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
+import { acquireQmdBackgroundLock, isQmdBackgroundLockHeld, qmdRunnerLastFinishedAt, qmdRunnerShouldSkip, recordQmdRunnerFinished, } from "../qmd-runner-admission.js";
 import { reindexAsync as defaultReindexAsync } from "../cli/reindex-async.js";
 /**
  * The runner reindexes after nearly every pass, and each reindex rewrites every
@@ -101,11 +105,12 @@ import { createPostSyncFlagEvaluator, POST_SYNC_FLAG_KEYS, } from "./sync-runner
 import { runPostSyncManifestUploads, } from "./sync-runner-manifest.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import { isTransientNetworkError, TRANSIENT_NETWORK_EXIT, } from "../lib/net-errors.js";
-import { PARTIAL_SYNC_EXIT, UNRESOLVED_COMPANY_EXIT, WATCH_RUNNER_ALREADY_OWNED_EXIT, WATCH_OWNER_LEASE_LOST_EXIT, } from "../lib/exit-codes.js";
+import { PARTIAL_SYNC_EXIT, UNRESOLVED_COMPANY_EXIT, PREFLIGHT_HALT_EXIT, WATCH_RUNNER_ALREADY_OWNED_EXIT, WATCH_OWNER_LEASE_LOST_EXIT, } from "../lib/exit-codes.js";
+import { SyncRunnerHashAudit } from "./sync-runner-audit.js";
 import { acquireWatchOwnerLease } from "../watch-owner-lease.js";
 import { startWatchParentExitMonitor } from "../watch-parent.js";
 import { describeError } from "../lib/describe-error.js";
-import { migratePersonalVaultJournal, PERSONAL_VAULT_JOURNAL_SLUG, getStateDir, repairJournalStateIfNeeded as defaultRepairJournalStateIfNeeded, } from "../journal.js";
+import { setAsyncJournalCompactionForWatchRunner, migratePersonalVaultJournal, PERSONAL_VAULT_JOURNAL_SLUG, getStateDir, repairJournalStateIfNeeded as defaultRepairJournalStateIfNeeded, } from "../journal.js";
 import { StateStoreLockError } from "../sync/state-store.js";
 import { resolveParallelSyncRollout } from "../sync/feature-flags.js";
 import { createRunnerEmitter, emitUncaughtRunnerError, notifyRunnerEmitObserver, } from "./sync-runner-events.js";
@@ -460,6 +465,9 @@ export function parseArgs(argv) {
     let scopeContentHashes;
     let eventPush = false;
     let lockTimeoutSec;
+    let qmdFullRefresh = false;
+    let auditHashOut;
+    const preflightRaw = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         switch (arg) {
@@ -562,6 +570,9 @@ export function parseArgs(argv) {
                 // @getindigo.ai identities for the first release.
                 eventPush = true;
                 break;
+            case "--qmd-full-refresh":
+                qmdFullRefresh = true;
+                break;
             case "--scope-path": {
                 const val = argv[++i];
                 if (!val)
@@ -634,6 +645,24 @@ export function parseArgs(argv) {
                 lockTimeoutSec = n;
                 break;
             }
+            case "--preflight-max-remote-deletes":
+            case "--preflight-max-local-deletes":
+            case "--preflight-max-pushes":
+            case "--preflight-max-pulls": {
+                const val = argv[++i];
+                if (val === undefined || !/^\d+$/.test(val) || !Number.isSafeInteger(Number(val))) {
+                    return { error: `${arg} requires a non-negative safe integer` };
+                }
+                preflightRaw.push(`${arg.slice("--preflight-max-".length)}=${val}`);
+                break;
+            }
+            case "--audit-hash-out": {
+                const filename = argv[++i];
+                if (!filename)
+                    return { error: "--audit-hash-out requires a file path" };
+                auditHashOut = filename;
+                break;
+            }
             default:
                 return { error: `Unknown argument: ${arg}` };
         }
@@ -651,6 +680,39 @@ export function parseArgs(argv) {
             error: "--personal and --skip-personal are contradictory",
         };
     }
+    const preflightKeys = [
+        "remote-deletes",
+        "local-deletes",
+        "pushes",
+        "pulls",
+    ];
+    let preflightLimits;
+    if (preflightRaw.length > 0) {
+        const parsedLimits = Object.fromEntries(preflightRaw.map((entry) => {
+            const separator = entry.indexOf("=");
+            const key = entry.slice(0, separator);
+            const value = entry.slice(separator + 1);
+            return [key, Number(value)];
+        }));
+        if (preflightRaw.length !== 4 ||
+            preflightKeys.some((key) => !Object.hasOwn(parsedLimits, key))) {
+            return { error: "all four --preflight-max-* limits are required together" };
+        }
+        if (!company || companies || personal || watch || direction !== "both" || scopePaths.length > 0) {
+            return { error: "preflight limits require an unscoped, company-scoped, both-direction one-shot" };
+        }
+        if (!auditHashOut)
+            return { error: "preflight limits require --audit-hash-out" };
+        preflightLimits = {
+            maxRemoteDeletes: parsedLimits["remote-deletes"],
+            maxLocalDeletes: parsedLimits["local-deletes"],
+            maxPushes: parsedLimits.pushes,
+            maxPulls: parsedLimits.pulls,
+        };
+    }
+    if (auditHashOut && (!company || companies || personal || watch || direction !== "both" || scopePaths.length > 0)) {
+        return { error: "--audit-hash-out requires an unscoped, company-scoped, both-direction one-shot" };
+    }
     if (!companies && !company && !personal) {
         return { error: "Pass --companies, --company <slug>, or --personal" };
     }
@@ -697,6 +759,9 @@ export function parseArgs(argv) {
         deleteScopePaths,
         eventPush,
         lockTimeoutSec,
+        ...(qmdFullRefresh ? { qmdFullRefresh: true } : {}),
+        ...(preflightLimits ? { preflightLimits } : {}),
+        ...(auditHashOut ? { auditHashOut } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -987,6 +1052,7 @@ export async function runRunner(argv, deps = {}) {
         stderr.write(`hq-sync-runner: ${parsed.error}\n`);
         return 1;
     }
+    setAsyncJournalCompactionForWatchRunner(parsed.watch);
     // A watch-loop pass also records its end-of-pass events for a host app that
     // does not read this stdout (the desktop app when `hq daemon` runs sync).
     const printEvent = createRunnerEmitter({ stdout, stderr });
@@ -1286,16 +1352,17 @@ export async function runRunner(argv, deps = {}) {
     for (const target of plan) {
         const journalSlug = target.journalSlug ?? target.slug;
         if (!journalTargets.has(journalSlug))
-            journalTargets.set(journalSlug, target.slug);
+            journalTargets.set(journalSlug, { company: target.slug, companyUid: target.uid });
     }
     // The one-time personal-vault seed below reads the legacy `personal` shard
     // even when no real company with that slug appears in the fanout plan. Give
     // that source the same bounded recovery before migration can open it. A
     // missing shard is a metadata-only no-op.
     if (!journalTargets.has("personal"))
-        journalTargets.set("personal", "personal");
+        journalTargets.set("personal", { company: "personal", companyUid: "" });
     const skippedJournalShards = new Set();
-    for (const [journalSlug, company] of journalTargets) {
+    for (const [journalSlug, targetIdentity] of journalTargets) {
+        const { company, companyUid } = targetIdentity;
         // Area-authoritative layouts rotate and repair through the watch loop's
         // bounded chore cursor.  Do not put every area behind this pass's startup
         // preflight: a realtime scoped pass must be able to start before a
@@ -1306,6 +1373,7 @@ export async function runRunner(argv, deps = {}) {
         }
         try {
             repairJournalStateIfNeeded(journalSlug, {
+                ...(companyUid ? { companyUid } : {}),
                 onProgress: ({ bytesRead, totalBytes }) => {
                     emit({
                         type: "maintenance-progress",
@@ -1333,8 +1401,12 @@ export async function runRunner(argv, deps = {}) {
             }
             emit({
                 type: "error",
-                message: err instanceof Error ? err.message : String(err),
-                path: "(local-state)",
+                ...(companyUid ? { companyUid } : {}),
+                errorClass: err instanceof Error && err.message.includes("HQSNAP4")
+                    ? "HQSNAP4EncodeError"
+                    : "JournalCompactionError",
+                message: "journal recovery failed",
+                path: "(journal)",
             });
             emitRunnerTerminalTelemetry({ status: "failed" });
             return 1;
@@ -1345,7 +1417,9 @@ export async function runRunner(argv, deps = {}) {
     // does NOT trigger a mass re-upload of the HQ overlay on first run. No-op
     // when the new journal already exists or the legacy one is absent, and
     // harmless even when the personal-vault slot is not in the plan.
-    if (!skippedJournalShards.has("personal") && !skippedJournalShards.has(PERSONAL_VAULT_JOURNAL_SLUG)) {
+    if (!parsed.preflightLimits &&
+        !skippedJournalShards.has("personal") &&
+        !skippedJournalShards.has(PERSONAL_VAULT_JOURNAL_SLUG)) {
         (deps.migratePersonalVaultJournal ?? migratePersonalVaultJournal)();
     }
     // The journal preflight and personal-vault seed are the point at which an
@@ -1360,6 +1434,16 @@ export async function runRunner(argv, deps = {}) {
     // ---- fanout -----------------------------------------------------------
     const syncFn = deps.sync ?? defaultSync;
     const shareFn = deps.share ?? defaultShare;
+    let audit;
+    if (parsed.auditHashOut) {
+        try {
+            audit = new SyncRunnerHashAudit(parsed.auditHashOut);
+        }
+        catch {
+            emit({ type: "error", path: "(audit)", message: "could not create hash audit output" });
+            return 1;
+        }
+    }
     let fanout;
     try {
         const heartbeatCompany = plan[0]?.slug ?? "(fanout)";
@@ -1403,6 +1487,9 @@ export async function runRunner(argv, deps = {}) {
             fanout = await executeCompanyFanout({
                 plan,
                 direction: parsed.direction,
+                ...(parsed.preflightLimits ? { preflightLimits: parsed.preflightLimits } : {}),
+                grantInventoryComplete: parsed.companies,
+                ...(audit ? { audit } : {}),
                 hqRoot: parsed.hqRoot,
                 onConflict: parsed.onConflict,
                 client,
@@ -1416,6 +1503,16 @@ export async function runRunner(argv, deps = {}) {
                     : {}),
                 syncFn,
                 shareFn,
+                ...(deps.onCatchupSkip ? { onCatchupSkip: deps.onCatchupSkip } : {}),
+                ...(deps.onCatchupGrantCompanies
+                    ? { onCatchupGrantCompanies: deps.onCatchupGrantCompanies }
+                    : {}),
+                ...(deps.onCatchupGrantVersion
+                    ? { onCatchupGrantVersion: deps.onCatchupGrantVersion }
+                    : {}),
+                ...(deps.onCatchupOntologyPush
+                    ? { onCatchupOntologyPush: deps.onCatchupOntologyPush }
+                    : {}),
                 resolveDeletePolicy,
                 emit,
                 ...(emitFanoutHeartbeat ? { onHeartbeat: emitFanoutHeartbeat } : {}),
@@ -1443,6 +1540,7 @@ export async function runRunner(argv, deps = {}) {
         finally {
             if (heartbeatTimer)
                 clearInterval(heartbeatTimer);
+            audit?.close();
         }
     }
     catch (err) {
@@ -1468,6 +1566,8 @@ export async function runRunner(argv, deps = {}) {
         }
         throw err;
     }
+    if (fanout.preflightHalted)
+        return PREFLIGHT_HALT_EXIT;
     const { errors, transientCompanies, allConflicts, meaningfulOutcomeCount } = fanout;
     const rollup = rollupAllComplete(plan, fanout.stateByCompany);
     deps.onPassResult?.({
@@ -1689,82 +1789,131 @@ export async function runRunner(argv, deps = {}) {
     const qmdChangedPaths = rollup.changedPaths.filter(isQmdIndexableContentPath);
     if (qmdChangedPaths.length > 0 &&
         postSyncFlags.isEnabled(POST_SYNC_FLAG_KEYS.qmdReindex)) {
-        try {
-            const qmdResult = (deps.qmdReindex ?? reindexAfterSync)(parsed.hqRoot, {
-                changedPaths: qmdChangedPaths,
-                forceCollectionRefresh: true,
-                signal: deps.qmdSignal,
-                ...(deps.qmdHeartbeat
-                    ? {
-                        onHeartbeat: deps.qmdHeartbeat,
-                        heartbeatIntervalMs: deps.qmdHeartbeatIntervalMs,
-                    }
-                    : {}),
-                log: ({ event, message, err, context }) => reportDiagnostic({
-                    component: "qmd-reindex",
-                    event,
-                    message,
-                    err,
-                    context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
-                }),
-            });
-            const completedQmdResult = await qmdResult;
-            void emitCloudTelemetry(client, {
-                eventName: "qmd_reindex_run",
-                source: "sync-runner",
-                sessionId: telemetrySessionId,
-                properties: {
-                    result: "completed",
-                    changedCount: qmdChangedPaths.length,
-                    qmdState: completedQmdResult.qmdAvailable ? "available" : "unavailable",
-                    collectionsAddedCount: completedQmdResult.collectionsAdded.length,
-                    pathDriftDetectedCount: completedQmdResult.pathDriftDetected?.length ?? 0,
-                    collectionsRepairedCount: completedQmdResult.collectionsRepaired?.length ?? 0,
-                    updateState: completedQmdResult.updated ? "updated" : "unchanged",
-                    embedState: completedQmdResult.embedded ? "embedded" : "not_embedded",
-                    dirtyState: completedQmdResult.pendingDirty ? "pending_dirty" : "clean",
-                    lockBusy: completedQmdResult.lockBusy === true ? 1 : 0,
-                    timedOut: completedQmdResult.timedOut === true ? 1 : 0,
-                    corruptionQuarantined: completedQmdResult.corruptionQuarantined === true ? 1 : 0,
-                    corruptionQuarantineFailed: completedQmdResult.corruptionQuarantineFailed === true ? 1 : 0,
-                },
-            }, {
-                claims,
-                log: (message) => reportDiagnostic({
-                    component: "telemetry-events",
-                    event: "runner.telemetry_events.nonfatal",
-                    message,
-                    context: { source: "sync-runner" },
-                }),
-            });
-        }
-        catch (err) {
+        const qmdAdmission = deps.qmdAdmission;
+        const qmdNow = qmdAdmission?.now ?? Date.now;
+        const qmdPlatform = qmdAdmission?.platform ?? process.platform;
+        const qmdEnv = qmdAdmission?.env ?? process.env;
+        const qmdHome = qmdAdmission?.home ?? qmdEnv.HOME ?? os.homedir();
+        const qmdRunnerFinishedByRoot = deps.qmdRunnerFinishedByRoot ?? (deps.qmdRunnerFinishedByRoot = new Map());
+        const qmdLockHeld = isQmdBackgroundLockHeld(qmdHome, { nowMs: qmdNow() });
+        if (qmdRunnerShouldSkip({
+            platform: qmdPlatform,
+            env: qmdEnv,
+            nowMs: qmdNow(),
+            lastFinishedAt: qmdRunnerLastFinishedAt(parsed.hqRoot, qmdRunnerFinishedByRoot),
+            lockHeld: qmdLockHeld,
+            fullRefresh: parsed.qmdFullRefresh,
+        })) {
             reportDiagnostic({
                 component: "qmd-reindex",
-                event: "runner.qmd_reindex.failed",
-                message: "post-sync qmd reindex threw",
-                err,
-                context: { hqRoot: parsed.hqRoot },
-            });
-            // Defensive: reindexAfterSync already swallows internally.
-            void emitCloudTelemetry(client, {
-                eventName: "qmd_reindex_run",
-                source: "sync-runner",
-                sessionId: telemetrySessionId,
-                properties: {
-                    result: "threw",
-                    changedCount: qmdChangedPaths.length,
-                },
-            }, {
-                claims,
-                log: (message) => reportDiagnostic({
-                    component: "telemetry-events",
-                    event: "runner.telemetry_events.nonfatal",
-                    message,
-                    context: { source: "sync-runner" },
-                }),
+                event: "runner.qmd_reindex.skipped_admission",
+                message: qmdLockHeld
+                    ? "post-sync qmd reindex skipped because the hq-cli background lock is held"
+                    : "post-sync qmd reindex skipped because the minimum interval has not elapsed",
+                context: { hqRoot: parsed.hqRoot, lockBusy: qmdLockHeld },
             });
         }
+        else {
+            try {
+                const releaseSharedLock = acquireQmdBackgroundLock(qmdHome, qmdNow());
+                if (!releaseSharedLock) {
+                    reportDiagnostic({
+                        component: "qmd-reindex",
+                        event: "runner.qmd_reindex.skipped_admission",
+                        message: "post-sync qmd reindex skipped because the hq-cli background lock could not be acquired",
+                        context: { hqRoot: parsed.hqRoot, lockBusy: true },
+                    });
+                }
+                else {
+                    let completedQmdResult;
+                    try {
+                        const qmdResult = (deps.qmdReindex ?? reindexAfterSync)(parsed.hqRoot, {
+                            changedPaths: qmdChangedPaths,
+                            forceCollectionRefresh: true,
+                            signal: deps.qmdSignal,
+                            ...(deps.qmdHeartbeat
+                                ? {
+                                    onHeartbeat: deps.qmdHeartbeat,
+                                    heartbeatIntervalMs: deps.qmdHeartbeatIntervalMs,
+                                }
+                                : {}),
+                            log: ({ event, message, err, context }) => reportDiagnostic({
+                                component: "qmd-reindex",
+                                event,
+                                message,
+                                err,
+                                context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
+                            }),
+                        });
+                        completedQmdResult = await qmdResult;
+                    }
+                    finally {
+                        releaseSharedLock();
+                    }
+                    if (completedQmdResult.qmdAvailable &&
+                        completedQmdResult.updated &&
+                        completedQmdResult.lockBusy !== true &&
+                        completedQmdResult.timedOut !== true) {
+                        recordQmdRunnerFinished(parsed.hqRoot, qmdNow(), qmdRunnerFinishedByRoot);
+                    }
+                    void emitCloudTelemetry(client, {
+                        eventName: "qmd_reindex_run",
+                        source: "sync-runner",
+                        sessionId: telemetrySessionId,
+                        properties: {
+                            result: "completed",
+                            changedCount: qmdChangedPaths.length,
+                            qmdState: completedQmdResult.qmdAvailable ? "available" : "unavailable",
+                            collectionsAddedCount: completedQmdResult.collectionsAdded.length,
+                            pathDriftDetectedCount: completedQmdResult.pathDriftDetected?.length ?? 0,
+                            collectionsRepairedCount: completedQmdResult.collectionsRepaired?.length ?? 0,
+                            updateState: completedQmdResult.updated ? "updated" : "unchanged",
+                            embedState: completedQmdResult.embedded ? "embedded" : "not_embedded",
+                            dirtyState: completedQmdResult.pendingDirty ? "pending_dirty" : "clean",
+                            lockBusy: completedQmdResult.lockBusy === true ? 1 : 0,
+                            timedOut: completedQmdResult.timedOut === true ? 1 : 0,
+                            corruptionQuarantined: completedQmdResult.corruptionQuarantined === true ? 1 : 0,
+                            corruptionQuarantineFailed: completedQmdResult.corruptionQuarantineFailed === true ? 1 : 0,
+                        },
+                    }, {
+                        claims,
+                        log: (message) => reportDiagnostic({
+                            component: "telemetry-events",
+                            event: "runner.telemetry_events.nonfatal",
+                            message,
+                            context: { source: "sync-runner" },
+                        }),
+                    });
+                }
+            }
+            catch (err) {
+                reportDiagnostic({
+                    component: "qmd-reindex",
+                    event: "runner.qmd_reindex.failed",
+                    message: "post-sync qmd reindex threw",
+                    err,
+                    context: { hqRoot: parsed.hqRoot },
+                });
+                // Defensive: reindexAfterSync already swallows internally.
+                void emitCloudTelemetry(client, {
+                    eventName: "qmd_reindex_run",
+                    source: "sync-runner",
+                    sessionId: telemetrySessionId,
+                    properties: {
+                        result: "threw",
+                        changedCount: qmdChangedPaths.length,
+                    },
+                }, {
+                    claims,
+                    log: (message) => reportDiagnostic({
+                        component: "telemetry-events",
+                        event: "runner.telemetry_events.nonfatal",
+                        message,
+                        context: { source: "sync-runner" },
+                    }),
+                });
+            }
+        }
     }
     // Post-sync conflict-ledger prune — also a best-effort tail step (runs AFTER
     // `all-complete`, never touches the exit code). The producers only append a
@@ -1989,6 +2138,16 @@ export function loopPassDeps(opts) {
         ...(opts.onJournalsReady ? { onJournalsReady: opts.onJournalsReady } : {}),
         ...(opts.onAppliedUpserts ? { onAppliedUpserts: opts.onAppliedUpserts } : {}),
         ...(opts.onAppliedDeletes ? { onAppliedDeletes: opts.onAppliedDeletes } : {}),
+        ...(opts.onCatchupSkip ? { onCatchupSkip: opts.onCatchupSkip } : {}),
+        ...(opts.onCatchupGrantCompanies
+            ? { onCatchupGrantCompanies: opts.onCatchupGrantCompanies }
+            : {}),
+        ...(opts.onCatchupGrantVersion
+            ? { onCatchupGrantVersion: opts.onCatchupGrantVersion }
+            : {}),
+        ...(opts.onCatchupOntologyPush
+            ? { onCatchupOntologyPush: opts.onCatchupOntologyPush }
+            : {}),
         ...(opts.watch ? { recordPassSummary: true } : {}),
         onPassResult: opts.onPassResult,
     };
@@ -2004,25 +2163,109 @@ function defaultParentExists(pid) {
 }
 export async function runRunnerWithLoop(argv, deps = {}) {
     const parsed = parseArgs(argv);
+    const watcherCatchupSkipStore = deps.watcherCatchupSkipStore ?? ("error" in parsed
+        ? undefined
+        : new WatcherCatchupSkipStore(watcherCatchupSkipStorePath(getStateDir(), parsed.hqRoot)));
+    const skipStoreHqRoot = "error" in parsed ? undefined : parsed.hqRoot;
+    let lastSkipStorePruneAt = 0;
+    let skipStorePruneWarningReported = false;
     const initialParentPid = process.ppid;
     const parentPid = "error" in parsed ? initialParentPid : (parsed.watchParentPid ?? initialParentPid);
     const runPassWithOperationLockAlreadyHeld = async (passArgv, fanoutHeartbeatIntervalMs, checkpoint, onJournalsReady, onAppliedUpserts, transferPriority = "chore", watch = false, qmdSignal, qmdHeartbeat, qmdHeartbeatIntervalMs, onAppliedDeletes) => {
         let result;
-        const exitCode = await runRunner(passArgv, loopPassDeps({
-            watch,
-            transferPriority,
-            qmdSignal,
-            qmdHeartbeat,
-            qmdHeartbeatIntervalMs,
-            fanoutHeartbeatIntervalMs,
-            checkpoint,
-            onJournalsReady,
-            onAppliedUpserts,
-            onAppliedDeletes,
-            onPassResult: (passResult) => {
-                result = passResult;
-            },
-        }));
+        const passStartedAt = Date.now();
+        const pendingCatchupSkips = [];
+        let exitCode = 1;
+        try {
+            exitCode = await runRunner(passArgv, loopPassDeps({
+                watch,
+                transferPriority,
+                qmdSignal,
+                qmdHeartbeat,
+                qmdHeartbeatIntervalMs,
+                fanoutHeartbeatIntervalMs,
+                checkpoint,
+                onJournalsReady,
+                onAppliedUpserts,
+                onAppliedDeletes,
+                ...(watcherCatchupSkipStore
+                    ? { onCatchupSkip: (record) => pendingCatchupSkips.push(record) }
+                    : {}),
+                ...(watcherCatchupSkipStore
+                    ? {
+                        onCatchupGrantCompanies: (companies) => watcherCatchupSkipStore.setCurrentGrantCompanies(companies),
+                    }
+                    : {}),
+                ...(watcherCatchupSkipStore
+                    ? {
+                        onCatchupOntologyPush: (company, enabled) => watcherCatchupSkipStore.setCurrentOntologyPush(company, enabled),
+                    }
+                    : {}),
+                ...(watcherCatchupSkipStore
+                    ? {
+                        onCatchupGrantVersion: (company, grantVersion) => watcherCatchupSkipStore.setCurrentGrantVersion(company, grantVersion),
+                    }
+                    : {}),
+                onPassResult: (passResult) => {
+                    result = passResult;
+                },
+            }));
+            if (exitCode === 0) {
+                watcherCatchupSkipStore?.clearResolvedGrantCompanies();
+                const companyIndex = passArgv.indexOf("--company");
+                const company = companyIndex >= 0 ? passArgv[companyIndex + 1]?.trim() : undefined;
+                if (company)
+                    watcherCatchupSkipStore?.clearUnresolvedCompany(company);
+            }
+        }
+        finally {
+            if (watcherCatchupSkipStore &&
+                skipStoreHqRoot &&
+                Date.now() - lastSkipStorePruneAt >= 6 * 60 * 60 * 1_000) {
+                watcherCatchupSkipStore.pruneMissing((record) => {
+                    const relativePath = record.company === "personal"
+                        ? record.path
+                        : ["companies", record.company, record.path].join("/");
+                    try {
+                        fs.lstatSync(localPathForVaultKey(skipStoreHqRoot, relativePath));
+                        return true;
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        if (code === "ENOENT" || code === "ENOTDIR")
+                            return false;
+                        if (!skipStorePruneWarningReported) {
+                            skipStorePruneWarningReported = true;
+                            process.stderr.write(`hq-sync-runner: catch-up skip pruning could not inspect a local path; retaining record: ${error instanceof Error ? error.message : String(error)}\n`);
+                        }
+                        return true;
+                    }
+                });
+                lastSkipStorePruneAt = Date.now();
+            }
+            if (watcherCatchupSkipStore) {
+                const recordedAt = Date.now();
+                const unique = new Map();
+                for (const record of pendingCatchupSkips) {
+                    unique.set(`${record.company}\u0000${record.path}`, record);
+                }
+                watcherCatchupSkipStore.commit([...unique.values()].map((record) => ({ ...record, recordedAt })));
+                const counts = {
+                    "archived-session-log": 0,
+                    "access-denied": 0,
+                    "cap-evicted": watcherCatchupSkipStore.takeCapEvictedCount(),
+                };
+                for (const record of unique.values())
+                    counts[record.reason] += 1;
+                process.stderr.write(`${JSON.stringify({
+                    type: "watcher-push-skip-summary",
+                    diagnostic: true,
+                    elapsedMs: Date.now() - passStartedAt,
+                    recordedPaths: unique.size,
+                    countsByReason: counts,
+                })}\n`);
+            }
+        }
         return { exitCode, ...(result ? { result } : {}) };
     };
     const runtime = {
@@ -2051,6 +2294,15 @@ export async function runRunnerWithLoop(argv, deps = {}) {
     const ownerLease = ownerResult.lease;
     const restoreOperationLockSignalReraise = suppressOperationLockSignalReraise();
     const protocolOutput = deps.stdout ?? process.stdout;
+    let latestSyncWorkState = {
+        passActive: false,
+        queuedWatcherPushes: 0,
+        inFlightWatcherPushes: 0,
+        pendingReceivers: 0,
+    };
+    const writeSyncWorkState = () => {
+        protocolOutput.write(`${JSON.stringify({ type: "sync-work-state", ...latestSyncWorkState })}\n`);
+    };
     let protocolStatus = { state: "starting" };
     const eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
     eventLoopDelay.enable();
@@ -2110,6 +2362,7 @@ export async function runRunnerWithLoop(argv, deps = {}) {
         else {
             protocolOutput.write(line);
         }
+        writeSyncWorkState();
         if (delay.maxMs > 2_000 && !stallReported) {
             stallReported = true;
             (deps.stderr ?? process.stderr).write(`${JSON.stringify({
@@ -2262,7 +2515,9 @@ export async function runRunnerWithLoop(argv, deps = {}) {
         while (!stopped) {
             const code = await runWatchLoop(argv, parsed, {
                 ...deps,
+                ...(watcherCatchupSkipStore ? { watcherCatchupSkipStore } : {}),
                 reportProtocolStatus,
+                onSyncWorkStateSnapshot: (snapshot) => { latestSyncWorkState = snapshot; },
                 onShutdownSignal: (handler) => {
                     innerShutdown = handler;
                     if (stopped)