dexbot 1.3.2 → 1.4.0

package/dist/modules/dexbot_maintenance_runtime.js

@@ -4,29 +4,49 @@ const { createHash } = require('./crypto/sync');
 const fs = require('fs');
 const { path } = require('./path_api');
 const { spawn } = require('child_process');
-const { BitShares, getNodeManager } = require('./bitshares_client');
 const chainOrders = require('./chain_orders');
-const { BroadcastUncertainError } = require('./dexbot_credential_client');
-const { Config, hasOpenOrdersSyncLoopMsSet, getOpenOrdersSyncLoopMs } = require('./config');
 const grid = require('./order/grid');
-const { isGridBloated, isGridBloatGraceActive, clearGridBloatFlag, loadGrid, recalculateGrid } = grid;
 const { ORDER_STATES, ORDER_TYPES, TIMING, BTS_PRECISION, NATIVE_CLIENT } = require('./constants');
 const { PATHS } = require('./paths');
-const { buildRuntimeScriptPath, isDistCodeRoot } = require('./launcher/runtime_entry');
-const { applyGridDivergenceCorrections, loadAmaCenterSnapshot, sleep } = require('./order/utils/system');
-const { isPm2Runtime } = require('./order/logger');
-const { getSharedMarketAdapterRuntime } = require('./launcher/market_adapter_runtime');
-const { resetMarketAdapterWhitelistCache, isBotDynamicWeightWhitelisted, } = require('./market_adapter_whitelist');
 const Format = require('./order/format');
-const { parseJsonWithComments } = require('./order/utils/system');
-const { cloneWeightDistribution, calculateOrderCreationFees, calculateSwapInAmount, floatToBlockchainInt, blockchainToFloat } = require('./order/utils/math');
-const { updateDynamicGridSnapshotSync } = require('../market_adapter/utils/dynamic_grid_snapshot');
-const { reconcileGridOrders } = require('./order/grid_reconcile');
-const { formatUnmatchedChainOrder, getSideBudget, correctAllPriceMismatches, isOrderOnChain, parseChainOrder } = require('./order/utils/order');
 const { getStorage } = require('./storage');
 const storage = getStorage();
-const { ensureDir, safeUnlink } = require('./utils/fs_utils');
 const fundRegistry = require('./fund_registry');
+const { BitShares } = require('./bitshares_client');
+const { BroadcastUncertainError } = require('./dexbot_credential_client');
+const { Config } = require('./config');
+function getNodeManager(...args) { return require('./bitshares_client').getNodeManager(...args); }
+function hasOpenOrdersSyncLoopMsSet(...args) { return require('./config').hasOpenOrdersSyncLoopMsSet(...args); }
+function getOpenOrdersSyncLoopMs(...args) { return require('./config').getOpenOrdersSyncLoopMs(...args); }
+function isGridBloated(...args) { return grid.isGridBloated(...args); }
+function isGridBloatGraceActive(...args) { return grid.isGridBloatGraceActive(...args); }
+function clearGridBloatFlag(...args) { return grid.clearGridBloatFlag(...args); }
+function recalculateGrid(...args) { return grid.recalculateGrid(...args); }
+function buildRuntimeScriptPath(...args) { return require('./launcher/runtime_entry').buildRuntimeScriptPath(...args); }
+function isDistCodeRoot(...args) { return require('./launcher/runtime_entry').isDistCodeRoot(...args); }
+function applyGridDivergenceCorrections(...args) { return require('./order/utils/system').applyGridDivergenceCorrections(...args); }
+function loadAmaCenterSnapshot(...args) { return require('./order/utils/system').loadAmaCenterSnapshot(...args); }
+function sleep(...args) { return require('./order/utils/system').sleep(...args); }
+function parseJsonWithComments(...args) { return require('./order/utils/system').parseJsonWithComments(...args); }
+function isPm2Runtime(...args) { return require('./order/logger').isPm2Runtime(...args); }
+function getSharedMarketAdapterRuntime(...args) { return require('./launcher/market_adapter_runtime').getSharedMarketAdapterRuntime(...args); }
+function resetMarketAdapterWhitelistCache(...args) { return require('./market_adapter_whitelist').resetMarketAdapterWhitelistCache(...args); }
+function isBotDynamicWeightWhitelisted(...args) { return require('./market_adapter_whitelist').isBotDynamicWeightWhitelisted(...args); }
+function getRuntimeSettingsKeys() { return require('./runtime_settings').RUNTIME_SETTINGS_KEYS; }
+function cloneWeightDistribution(...args) { return require('./order/utils/math').cloneWeightDistribution(...args); }
+function calculateOrderCreationFees(...args) { return require('./order/utils/math').calculateOrderCreationFees(...args); }
+function calculateSwapInAmount(...args) { return require('./order/utils/math').calculateSwapInAmount(...args); }
+function floatToBlockchainInt(...args) { return require('./order/utils/math').floatToBlockchainInt(...args); }
+function blockchainToFloat(...args) { return require('./order/utils/math').blockchainToFloat(...args); }
+function updateDynamicGridSnapshotSync(...args) { return require('../market_adapter/utils/dynamic_grid_snapshot').updateDynamicGridSnapshotSync(...args); }
+function reconcileGridOrders(...args) { return require('./order/grid_reconcile').reconcileGridOrders(...args); }
+function formatUnmatchedChainOrder(...args) { return require('./order/utils/order').formatUnmatchedChainOrder(...args); }
+function getSideBudget(...args) { return require('./order/utils/order').getSideBudget(...args); }
+function correctAllPriceMismatches(...args) { return require('./order/utils/order').correctAllPriceMismatches(...args); }
+function isOrderOnChain(...args) { return require('./order/utils/order').isOrderOnChain(...args); }
+function parseChainOrder(...args) { return require('./order/utils/order').parseChainOrder(...args); }
+const { ensureDir, safeUnlink } = require('./utils/fs_utils');
+const { getErrorMessage } = require('./utils/errors');
 const CODE_ROOT = path.join(__dirname, '..');
 const PROFILES_DIR = PATHS.PROFILES_DIR;
 const PROFILES_BOTS_FILE = PATHS.PROFILES.BOTS_JSON;
@@ -118,7 +138,7 @@ function countLiveGridOrders(manager, type) {
         return 0;
     const active = manager.getOrdersByTypeAndState?.(type, ORDER_STATES.ACTIVE) || [];
     const partial = manager.getOrdersByTypeAndState?.(type, ORDER_STATES.PARTIAL) || [];
-    return active.concat(partial).filter(o => o?.orderId).length;
+    return active.concat(partial).filter((o) => o?.orderId).length;
 }
 function getTargetActiveOrders(config, side) {
     const configured = Number(config?.activeOrders?.[side]);
@@ -219,7 +239,7 @@ async function maybeRunTargetedDriftReconciliation(bot, context) {
         return true;
     }
     catch (err) {
-        bot._warn(`[TARGETED-SYNC] Failed during ${context}: ${err.message}`);
+        bot._warn(`[TARGETED-SYNC] Failed during ${context}: ${getErrorMessage(err)}`);
         return false;
     }
 }
@@ -409,7 +429,7 @@ async function syncMarketAdapterOnPeriodicConfigCheck(bot, context = 'periodic')
         }
         catch (err) {
             pm2QueryFailed = true;
-            bot._warn(`Could not query PM2 for ${MARKET_ADAPTER_APP_NAME}: ${err.message}. Using a direct PM2 action.`);
+            bot._warn(`Could not query PM2 for ${MARKET_ADAPTER_APP_NAME}: ${getErrorMessage(err)}. Using a direct PM2 action.`);
         }
         // Cross-reference config-active bots against actually running PM2 processes
         // so we don't start the adapter for configured AMA bots that aren't running.
@@ -462,14 +482,14 @@ async function syncMarketAdapterOnPeriodicConfigCheck(bot, context = 'periodic')
         };
     }
     catch (err) {
-        bot._warn(`Market adapter watchdog failed during ${context}: ${err.message}`);
+        bot._warn(`Market adapter watchdog failed during ${context}: ${getErrorMessage(err)}`);
         return {
             changed: false,
             required: false,
             running: false,
             started: false,
             stopped: false,
-            error: err.message,
+            error: getErrorMessage(err),
         };
     }
     finally {
@@ -589,7 +609,7 @@ function buildGridResyncMetadata(reason) {
     return {
         ...defaults,
         ...marketAdapterUnknown,
-        ...GRID_RESYNC_REASONS[resetSource],
+        ...(GRID_RESYNC_REASONS[resetSource] || {}),
         resetSource,
     };
 }
@@ -709,19 +729,28 @@ function performGridResync(bot, options = {}) {
                 const content = storage.readFile(PROFILES_BOTS_FILE);
                 const allBotsConfig = parseJsonWithComments(content).bots || [];
                 const myName = self.config.name;
-                const updatedBot = allBotsConfig.find(b => b.name === myName);
+                const updatedBot = allBotsConfig.find((b) => b.name === myName);
                 if (updatedBot) {
                     self._log(`Reloaded configuration for bot '${myName}'`);
                     const oldKey = self.config.botKey;
                     const oldIndex = self.config.botIndex;
-                    self.config = { ...updatedBot, botKey: oldKey, botIndex: oldIndex };
+                    // Preserve runtime-only properties set by the constructor
+                    // (timing, gridLimits, feeParams, etc.) that are not present
+                    // in the raw profile from bots.json.
+                    const runtimeProps = {};
+                    for (const key of getRuntimeSettingsKeys()) {
+                        if (self.config[key] !== undefined) {
+                            runtimeProps[key] = self.config[key];
+                        }
+                    }
+                    self.config = { ...updatedBot, botKey: oldKey, botIndex: oldIndex, ...runtimeProps };
                     self.manager.config = { ...self.manager.config, ...self.config };
                     self._baseWeightDistribution = cloneWeightDistribution(updatedBot.weightDistribution, self._baseWeightDistribution);
                     refreshDynamicWeightDistribution(self, 'grid resync');
                 }
             }
             catch (e) {
-                self._warn(`Failed to reload config during resync (using current settings): ${e.message}`);
+                self._warn(`Failed to reload config during resync (using current settings): ${getErrorMessage(e)}`);
             }
             if (refreshCenterPrice) {
                 if (promoteAmaCenterSnapshotForGridReset(self.config?.botKey)) {
@@ -766,7 +795,7 @@ function performGridResync(bot, options = {}) {
                     });
                 }
                 catch (_dustErr) {
-                    self._warn(`[DUST] Post-resync dust cancel failed: ${_dustErr.message}`);
+                    self._warn(`[DUST] Post-resync dust cancel failed: ${getErrorMessage(_dustErr)}`);
                 }
             }
             // Clear unmatched chain orders after a successful rebuild.
@@ -780,7 +809,7 @@ function performGridResync(bot, options = {}) {
             }
         }
         catch (err) {
-            self._log(`Error during triggered resync: ${err.message}`, 'error');
+            self._log(`Error during triggered resync: ${getErrorMessage(err)}`, 'error');
         }
         finally {
             self.manager.finishBootstrap();
@@ -851,8 +880,8 @@ async function setupTriggerFileDetection(bot) {
                                 if (!ok) {
                                     bot._warn('Runtime trigger reset failed; retaining existing grid state.');
                                 }
-                            }).catch(err => {
-                                bot._warn(`Trigger reset lock error: ${err.message}`);
+                            }).catch((err) => {
+                                bot._warn(`Trigger reset lock error: ${getErrorMessage(err)}`);
                                 bot.manager._recoveryState = { ...bot.manager._recoveryState, lastFailureAt: Date.now() };
                             });
                         }, 200);
@@ -860,12 +889,12 @@ async function setupTriggerFileDetection(bot) {
                 }
             }
             catch (err) {
-                bot._warn(`fs.watch handler error: ${err && err.message ? err.message : err}`);
+                bot._warn(`fs.watch handler error: ${err && getErrorMessage(err) ? getErrorMessage(err) : err}`);
             }
         });
     }
     catch (err) {
-        bot._warn(`Failed to setup file watcher: ${err.message}`);
+        bot._warn(`Failed to setup file watcher: ${getErrorMessage(err)}`);
     }
 }
 /**
@@ -941,12 +970,12 @@ function startOpenOrdersSyncLoop(bot) {
                 }
             }
             catch (err) {
-                bot._warn(`Order manager loop error: ${err.message}`);
+                bot._warn(`Order manager loop error: ${getErrorMessage(err)}`);
             }
             await sleep(loopDelayMs);
         }
-    })().catch(err => {
-        bot._warn(`Open-orders sync loop failed: ${err && err.message ? err.message : err}`);
+    })().catch((err) => {
+        bot._warn(`Open-orders sync loop failed: ${err && getErrorMessage(err) ? getErrorMessage(err) : err}`);
     }).finally(() => {
         bot._mainLoopPromise = null;
     });
@@ -982,12 +1011,12 @@ function setupBlockchainFetchInterval(bot) {
             }
         }
         catch (_err) {
-            bot?._warn?.(`Registry unavailable for shared-account interval check: ${_err.message}`);
+            bot?._warn?.(`Registry unavailable for shared-account interval check: ${getErrorMessage(_err)}`);
         }
     }
     syncMarketAdapterOnPeriodicConfigCheck(bot, 'startup blockchain fetch setup')
         .catch((err) => {
-        bot._warn(`Market adapter watchdog failed during startup blockchain fetch setup: ${err.message}`);
+        bot._warn(`Market adapter watchdog failed during startup blockchain fetch setup: ${getErrorMessage(err)}`);
     });
     if (bot._blockchainFetchInterval !== null && bot._blockchainFetchInterval !== undefined) {
         stopBlockchainFetchInterval(bot);
@@ -1058,14 +1087,14 @@ function setupBlockchainFetchInterval(bot) {
                             }
                         }
                         catch (err) {
-                            bot._warn(`Error reading open orders during periodic fetch: ${err.message}`);
+                            bot._warn(`Error reading open orders during periodic fetch: ${getErrorMessage(err)}`);
                         }
                     }
                     await performPeriodicGridChecks(bot);
                 });
             }
             catch (err) {
-                bot._warn(`Error during periodic blockchain fetch: ${err && err.message ? err.message : err}`);
+                bot._warn(`Error during periodic blockchain fetch: ${err && getErrorMessage(err) ? getErrorMessage(err) : err}`);
             }
         }
         finally {
@@ -1096,7 +1125,7 @@ function stopBlockchainFetchInterval(bot) {
  * @param {string} [context='shutdown'] - Context label for logging
  * @returns {Promise<import('./types').MarketAdapterReleaseResult>}
  */
-async function releaseMarketAdapterRuntime(bot, botId, context = 'shutdown') {
+async function releaseMarketAdapterRuntime(_bot, botId, context = 'shutdown') {
     if (isPm2Runtime()) {
         return { released: false, mode: 'pm2' };
     }
@@ -1174,8 +1203,8 @@ function scheduleMaintenanceAfterIdle(ctx, context, options = {}) {
         if (ctx._shuttingDown)
             return;
         ctx._runGridMaintenance(context, timerOptions)
-            .catch(err => {
-            ctx._warn(`Deferred ${context} grid maintenance failed: ${err.message}`);
+            .catch((err) => {
+            ctx._warn(`Deferred ${context} grid maintenance failed: ${getErrorMessage(err)}`);
             if (ctx.manager) {
                 ctx.manager._recoveryState = { ...ctx.manager._recoveryState, lastFailureAt: Date.now() };
             }
@@ -1217,8 +1246,8 @@ function scheduleDeferredGridResync(ctx, options = {}) {
                     : 'grid resync rejected or failed';
                 ctx._warn(`Deferred trigger reset blocked: ${reason}; retaining existing grid state.`);
             }
-        }).catch(err => {
-            ctx._warn(`Deferred trigger reset lock error: ${err.message}`);
+        }).catch((err) => {
+            ctx._warn(`Deferred trigger reset lock error: ${getErrorMessage(err)}`);
             if (ctx.manager) {
                 ctx.manager._recoveryState = { ...ctx.manager._recoveryState, lastFailureAt: Date.now() };
             }
@@ -1273,7 +1302,7 @@ async function executeMaintenanceLogic(bot, context) {
                 bot._log(`[GRID-BLOAT] Grid size ${d.gridSize} still exceeds expected maximum ${d.maxAllowed} ` +
                     `after grace period (${grace.graceMs}ms). Triggering structural resync.`, 'warn');
                 bot.manager.requestStructuralGridResync('grid-bloat-persistent', { reason: `Grid size ${d.gridSize} still exceeds max ${d.maxAllowed} after grace` }).catch((err) => {
-                    bot.manager?.logger?.log?.(`[GRID-BLOAT] Structural resync request failed: ${err.message}`, 'error');
+                    bot.manager?.logger?.log?.(`[GRID-BLOAT] Structural resync request failed: ${getErrorMessage(err)}`, 'error');
                 });
             }
             else {
@@ -1299,7 +1328,7 @@ async function executeMaintenanceLogic(bot, context) {
                 bot._log('[LIGHTWEIGHT-SYNC] Skipped: manager assets not available', 'debug');
             }
             else {
-                const chainOrdersCount = chainOpenOrdersResult.filter(o => parseChainOrder(o, assets) !== null).length;
+                const chainOrdersCount = chainOpenOrdersResult.filter((o) => parseChainOrder(o, assets) !== null).length;
                 const gridActive = Array.from(bot.manager.orders.values()).filter((o) => isOrderOnChain(o)).length;
                 const diff = Math.abs(chainOrdersCount - gridActive);
                 if (diff > 2) {
@@ -1316,7 +1345,7 @@ async function executeMaintenanceLogic(bot, context) {
             }
         }
         catch (e) {
-            bot._log(`[LIGHTWEIGHT-SYNC] Check failed: ${e.message}`, 'debug');
+            bot._log(`[LIGHTWEIGHT-SYNC] Check failed: ${getErrorMessage(e)}`, 'debug');
         }
     }
     // Process any price corrections queued by prior sync operations before
@@ -1388,12 +1417,12 @@ async function executeMaintenanceLogic(bot, context) {
                     bot._log(`Grid divergence corrections applied during ${context}`);
                 }
                 catch (err) {
-                    bot._warn(`Error applying divergence corrections during ${context}: ${err.message}`);
+                    bot._warn(`Error applying divergence corrections during ${context}: ${getErrorMessage(err)}`);
                 }
             }
         }
         catch (err) {
-            bot._warn(`Error running divergence check during ${context}: ${err.message}`);
+            bot._warn(`Error running divergence check during ${context}: ${getErrorMessage(err)}`);
         }
         const spreadResult = await bot.manager.checkSpreadCondition(BitShares, bot.updateOrdersOnChainPlan.bind(bot));
         if (await bot._abortFlowIfIllegalState(`${context} spread check`))
@@ -1431,7 +1460,7 @@ async function executeMaintenanceLogic(bot, context) {
 async function cancelOrderWithNodeFallback(bot, order) {
     try {
         const nodeManager = getNodeManager();
-        const nodes = nodeManager.getHealthyNodes();
+        const nodes = nodeManager?.getHealthyNodes() ?? [];
         const fallbackNodes = nodes.length > 1 ? nodes.slice(1) : undefined;
         return await chainOrders.cancelOrder(bot.account, bot.privateKey, order.orderId, fallbackNodes
             ? {
@@ -1481,13 +1510,13 @@ async function cancelDustOrders(bot, { buy: buyDust = [], sell: sellDust = [] }
                 }
             }
             catch (refetchErr) {
-                bot._warn(`[DUST] Cancel succeeded but refetch failed for ${order.id} (${order.orderId}): ${refetchErr.message}`);
+                bot._warn(`[DUST] Cancel succeeded but refetch failed for ${order.id} (${order.orderId}): ${getErrorMessage(refetchErr)}`);
             }
             syntheticFills.push({ ...order, isPartial: true, isDelayedRotationTrigger: true });
             bot._log(`[DUST] Cancelled ${order.id} (${order.orderId}) size=${order.size}`, 'debug');
         }
         catch (err) {
-            const errMsg = err?.message || '';
+            const errMsg = getErrorMessage(err) || '';
             if (isOrderDoesNotExistError(errMsg, order.orderId)) {
                 syntheticFills.push({ ...order, isPartial: true, isDelayedRotationTrigger: true });
                 bot._log(`[DUST] Order ${order.id} (${order.orderId}) already gone from chain`, 'debug');
@@ -1499,7 +1528,7 @@ async function cancelDustOrders(bot, { buy: buyDust = [], sell: sellDust = [] }
     }
     if (syntheticFills.length === 0)
         return { cancelledCount: 0, batchResult: null };
-    const result = await bot._processFillsWithBatching(syntheticFills, new Set(), `dust cancel [${syntheticFills.map(o => o.id).join(', ')}]`);
+    const result = await bot._processFillsWithBatching(syntheticFills, new Set(), `dust cancel [${syntheticFills.map((o) => o.id).join(', ')}]`);
     if (!result.aborted) {
         await bot.manager.persistGrid();
     }
@@ -1542,7 +1571,7 @@ async function runGridMaintenance(bot, context = 'periodic', options = {}) {
         });
     }
     catch (err) {
-        bot._warn(`Error during ${context} grid maintenance: ${err.message}`);
+        bot._warn(`Error during ${context} grid maintenance: ${getErrorMessage(err)}`);
         throw err;
     }
 }
@@ -1623,7 +1652,7 @@ async function acquireBts(bot, deficit) {
             continue;
         try {
             const pools = await BitShares.db.get_liquidity_pools_by_both_assets(asset.id, coreAssetId);
-            const validPools = Array.isArray(pools) ? pools.filter(p => p?.id) : [];
+            const validPools = Array.isArray(pools) ? pools.filter((p) => p?.id) : [];
             const poolData = validPools.length
                 ? validPools.sort((a, b) => {
                     const getBtsBal = (p) => {
@@ -1649,7 +1678,7 @@ async function acquireBts(bot, deficit) {
             candidates.push({ asset, poolId: poolData.id, sellAmount, expectedReceive, priceImpact: sellAmount / assetReserve });
         }
         catch (e) {
-            bot._log(`[BTS-ACQ] Pool lookup failed for ${asset?.symbol}: ${e.message}`, 'debug');
+            bot._log(`[BTS-ACQ] Pool lookup failed for ${asset?.symbol}: ${getErrorMessage(e)}`, 'debug');
         }
     }
     if (candidates.length === 0) {
@@ -1673,7 +1702,7 @@ async function acquireBts(bot, deficit) {
         }
     }
     catch (err) {
-        bot._log(`[BTS-ACQ] Swap broadcast failed: ${err.message}`, 'error');
+        bot._log(`[BTS-ACQ] Swap broadcast failed: ${getErrorMessage(err)}`, 'error');
         return;
     }
     const orderType = (best.asset.id === bot.assets?.assetA?.id) ? 'sell' : 'buy';
@@ -1688,6 +1717,208 @@ async function acquireBts(bot, deficit) {
     // if the chain balance is still below the trigger threshold.
     bot._log(`[BTS-ACQ] Acquired ~${Format.formatAmount8(best.expectedReceive)} BTS: sold ${Format.formatAmount8(best.sellAmount)} ${best.asset.symbol} via pool ${best.poolId}`, 'info');
 }
+/**
+ * Run a single dust health check cycle.
+ * @param {import('./dexbot_class').DEXBot} bot
+ */
+async function runDustHealthCheck(bot) {
+    if (bot._shuttingDown || !bot.manager)
+        return;
+    try {
+        const health = await bot.manager.checkGridHealth(bot.updateOrdersOnChainPlan?.bind(bot));
+        const buyDust = health.buyDustOrders || [];
+        const sellDust = health.sellDustOrders || [];
+        const totalDust = buyDust.length + sellDust.length;
+        if (totalDust > 0) {
+            bot._log(`[DUST] Health check: ${totalDust} dust order(s) (buy=${buyDust.length}, sell=${sellDust.length})`);
+            const lock = bot.manager._fillProcessingLock;
+            if (lock && typeof lock.acquire === 'function') {
+                await lock.acquire(async () => {
+                    await bot._cancelDustOrders({
+                        buy: health.buyDustOrders,
+                        sell: health.sellDustOrders,
+                    });
+                }, { timeout: TIMING.DUST_CANCEL_TIMEOUT_MS });
+            }
+            else {
+                bot._warn('[DUST] Fill lock unavailable — cancelling dust without lock (potential race)');
+                await bot._cancelDustOrders({
+                    buy: health.buyDustOrders,
+                    sell: health.sellDustOrders,
+                });
+            }
+        }
+    }
+    catch (err) {
+        if (getErrorMessage(err).includes('Lock acquisition timeout')) {
+            bot._warn('[DUST] Lock busy, skipping dust cancel this cycle (retry in 5 min)');
+        }
+        else {
+            bot._warn(`[DUST] Health check error (retry in 5 min): ${getErrorMessage(err)}`);
+        }
+    }
+}
+/**
+ * Set up the periodic dust health check interval.
+ * @param {import('./dexbot_class').DEXBot} bot
+ */
+function setupDustHealthCheckInterval(bot) {
+    bot._dustHealthCheckTimer = setInterval(() => {
+        runDustHealthCheck(bot);
+    }, TIMING.DUST_HEALTH_CHECK_INTERVAL_MS);
+    if (typeof bot._dustHealthCheckTimer?.unref === 'function') {
+        bot._dustHealthCheckTimer.unref();
+    }
+}
+/**
+ * Request a full grid reset from fresh on-chain state.
+ * @param {import('./dexbot_class').DEXBot} bot
+ * @param {string} [reason='structural change']
+ * @param {{refreshCenterPrice?: boolean}} [options={}]
+ * @returns {Promise<Object>}
+ */
+async function requestGridReset(bot, reason = 'structural change', options = {}) {
+    if (!bot.manager || typeof bot._performGridResync !== 'function') {
+        return { skipped: true, reason: 'grid resync unavailable' };
+    }
+    const message = reason ? `[CR-RESET] ${reason}` : '[CR-RESET] grid reset requested';
+    bot._log(`${message}; rebuilding grid from fresh on-chain state`, 'info');
+    const resetOptions = {
+        ...options,
+        refreshCenterPrice: options.refreshCenterPrice !== false,
+    };
+    if (!bot.manager._fillProcessingLock || bot.manager._fillProcessingLock.isReentrant()) {
+        return performGridResync(bot, resetOptions);
+    }
+    return bot.manager._fillProcessingLock.acquire(async () => performGridResync(bot, resetOptions));
+}
+/**
+ * Wire the structural grid resync request handler on the manager.
+ * @param {import('./dexbot_class').DEXBot} bot
+ */
+function wireStructuralGridResyncRequest(bot) {
+    if (!bot.manager || bot.manager.requestStructuralGridResync)
+        return;
+    bot.manager.requestStructuralGridResync = async (reason = 'structural recovery', details = {}) => {
+        if (bot._shuttingDown) {
+            return { skipped: true, reason: 'shutting down' };
+        }
+        if (bot._structuralGridResyncRunning || bot._structuralGridResyncTimer) {
+            return { skipped: true, reason: 'structural grid resync already scheduled' };
+        }
+        const unmatchedCount = Array.isArray(details?.unmatchedChainOrders)
+            ? details.unmatchedChainOrders.length
+            : 0;
+        bot._structuralGridResyncTimer = setTimeout(async () => {
+            bot._structuralGridResyncTimer = null;
+            if (bot._shuttingDown)
+                return;
+            bot._structuralGridResyncRunning = true;
+            try {
+                const persistedResult = await bot._recoverFromPersistedGrid();
+                if (persistedResult.success) {
+                    if (bot.manager?._recoveryState) {
+                        bot.manager._recoveryState = { ...bot.manager._recoveryState, attemptCount: 0, lastAttemptAt: 0, lastFailureAt: 0 };
+                    }
+                    return;
+                }
+                const suffix = unmatchedCount > 0 ? ` (${unmatchedCount} unmatched chain order(s))` : '';
+                bot._warn(`[RECOVERY] Running structural full grid resync for ${reason}${suffix}`);
+                const resetResult = await bot.requestGridReset('rms_structural_grid_resync', {
+                    refreshCenterPrice: true,
+                });
+                if (resetResult && bot.manager?._recoveryState) {
+                    bot.manager._recoveryState = { ...bot.manager._recoveryState, attemptCount: 0, lastAttemptAt: 0, lastFailureAt: 0 };
+                }
+            }
+            catch (err) {
+                bot._warn(`[RECOVERY] Structural full grid resync failed: ${getErrorMessage(err)}`);
+            }
+            finally {
+                bot._structuralGridResyncRunning = false;
+                if (bot.manager?._recoveryState) {
+                    bot.manager._recoveryState = { ...bot.manager._recoveryState, structuralResyncRequested: false };
+                }
+            }
+        }, 0);
+        return { scheduled: true };
+    };
+}
+/**
+ * Get current pipeline signal state for congestion checks.
+ * @param {import('./dexbot_class').DEXBot} bot
+ * @returns {Object}
+ */
+function getPipelineSignals(bot) {
+    bot.manager?._cleanExpiredLocks?.();
+    return {
+        incomingFillQueueLength: bot._incomingFillQueue.length,
+        shadowLocks: bot.manager?.shadowOrderIds?.size || 0,
+        batchInFlight: bot._batchInFlight,
+        recoveryInFlight: bot._recoverySyncInFlight,
+        broadcasting: bot.manager?.isBroadcastingActive?.() || false
+    };
+}
+/**
+ * Mark that grid activity occurred (updates idle timer).
+ * @param {import('./dexbot_class').DEXBot} bot
+ * @param {string} [reason='activity']
+ */
+function markGridActivity(bot, reason = 'activity') {
+    bot._lastGridActivityAt = Date.now();
+    bot.manager?.logger?.log?.(`[MAINT-IDLE] Activity observed: ${reason}`, 'debug');
+}
+/**
+ * Get current metrics for monitoring and debugging.
+ * @param {import('./dexbot_class').DEXBot} bot
+ * @returns {Object}
+ */
+function getMetrics(bot) {
+    bot.manager?._cleanExpiredLocks?.();
+    return {
+        ...bot._metrics,
+        queueDepth: bot._incomingFillQueue.length,
+        fillProcessingLockActive: bot.manager?._fillProcessingLock?.isLocked() || false,
+        divergenceLockActive: bot.manager?._divergenceLock?.isLocked() || false,
+        shadowLocksActive: bot.manager?.shadowOrderIds?.size || 0,
+        recoveryExhaustedAt: bot.manager?._recoveryExhaustedAt || null,
+        recentFillsTracked: bot._recentlyProcessedFills.size
+    };
+}
+/**
+ * Read open orders from chain, sync with local state, and process any fills found.
+ * @param {import('./dexbot_class').DEXBot} bot
+ * @param {string} tag - Context label for logging
+ * @returns {Promise<Object>}
+ */
+async function syncOpenOrdersAndProcessFills(bot, tag) {
+    if (!bot.accountId || bot.config?.dryRun) {
+        return { syncResult: null, aborted: false, hasUnmatched: 0, openOrders: null };
+    }
+    try {
+        let openOrders = await chainOrders.readOpenOrders(bot.accountId);
+        const syncResult = await bot.manager.synchronizeWithChain(openOrders, 'readOpenOrders');
+        let aborted = false;
+        if (syncResult?.filledOrders?.length > 0) {
+            bot._refreshDynamicWeightDistribution(`${tag} sync-fill`);
+            bot._log(`[SYNC-CHAIN] ${syncResult.filledOrders.length} filled order(s) found during ${tag}`, 'info');
+            const batchResult = await bot._processFillsWithBatching(syncResult.filledOrders, new Set(), `${tag} sync-fill`);
+            if (!batchResult?.aborted) {
+                openOrders = await chainOrders.readOpenOrders(bot.accountId);
+                await bot.manager.synchronizeWithChain(openOrders, 'readOpenOrders');
+            }
+            else {
+                aborted = true;
+            }
+        }
+        const hasUnmatched = syncResult?.unmatchedChainOrders?.length || 0;
+        return { syncResult, aborted, hasUnmatched, openOrders };
+    }
+    catch (err) {
+        bot._warn(`[SYNC-CHAIN] Open-orders sync failed during ${tag}: ${getErrorMessage(err)}`);
+        return { syncResult: null, aborted: true, hasUnmatched: -1, openOrders: null };
+    }
+}
 module.exports = {
     loadBotsConfigSnapshot,
     refreshDynamicWeightDistribution,
@@ -1713,5 +1944,13 @@ module.exports = {
     usesAmaGridPrice,
     checkBtsBalanceAndAcquire,
     acquireBts,
+    runDustHealthCheck,
+    setupDustHealthCheckInterval,
+    requestGridReset,
+    wireStructuralGridResyncRequest,
+    getPipelineSignals,
+    markGridActivity,
+    getMetrics,
+    syncOpenOrdersAndProcessFills,
 };
 //# sourceMappingURL=dexbot_maintenance_runtime.js.map