dexbot 1.5.3 → 1.6.0

package/dist/modules/dexbot_maintenance_runtime.js

@@ -12,6 +12,7 @@ import { path } from './path_api.js';
 import * as chainOrders from './chain_orders.js';
 import * as grid from './order/grid.js';
 import { ORDER_STATES, ORDER_TYPES, TIMING, BTS_PRECISION, NATIVE_CLIENT } from './constants.js';
+import { BOT_LIVE_CONFIG_KEYS } from './runtime_settings.js';
 import { acquireIfNotHeld } from './order/async_lock.js';
 const { readOpenOrdersGuarded } = chainOrders;
 import { PATHS } from './paths.js';
@@ -57,7 +58,12 @@ function updateDynamicGridSnapshotSync(...args) { return require('../market_adap
 // would be circular; at call time both modules are fully loaded.
 function scheduleFillConsumerRestartFn(...args) { return require('./dexbot_fill_runtime').scheduleFillConsumerRestart(...args); }
 function reconcileGridOrders(...args) { return require('./order/grid_reconcile').reconcileGridOrders(...args); }
+function resolveReserveCount(...args) { return require('./order/utils/order').resolveReserveCount(...args); }
+function reserveEdgeIdSet(...args) { return require('./order/utils/order').reserveEdgeIdSet(...args); }
+function liveWindowIdSet(...args) { return require('./order/utils/order').liveWindowIdSet(...args); }
+function resolveLiveReserveEdgeAnchorPrice(...args) { return require('./order/utils/order').resolveLiveReserveEdgeAnchorPrice(...args); }
 function formatUnmatchedChainOrder(...args) { return require('./order/utils/order').formatUnmatchedChainOrder(...args); }
+function isNonBlockingUnmatchedOrder(...args) { return require('./order/utils/order').isNonBlockingUnmatchedOrder(...args); }
 function getSideBudget(...args) { return require('./order/utils/order').getSideBudget(...args); }
 function getActiveOrdersTotal(config) { return require('./order/utils/order').getActiveOrdersTotal(config); }
 function correctAllPriceMismatches(...args) { return require('./order/utils/order').correctAllPriceMismatches(...args); }
@@ -147,6 +153,369 @@ function runtimeConfigNeedsMarketAdapter(snapshot, config) {
     }
     return usesAmaGridPrice(config);
 }
+/**
+ * Live bot-config allowlist (BOT_LIVE_CONFIG_KEYS) is defined once in
+ * runtime_settings.ts (shared with the `dexbot bot` editor hint) and
+ * statically imported above. Everything outside it is hint-only:
+ * geometry needs `dexbot reset <bot>`, identity needs a restart.
+ */
+/**
+ * Top-level entry keys excluded from the live bot-config fingerprint.
+ * botKey/botIndex are runtime-assigned, accountId is auto-saved next to
+ * preferredAccount after the first chain resolution (not a user edit).
+ */
+const BOT_CONFIG_FINGERPRINT_IGNORED_KEYS = Object.freeze([
+    'botKey',
+    'botIndex',
+    'accountId',
+]);
+/**
+ * Deterministic JSON stringify with recursively sorted object keys.
+ * Key order in bots.json must not count as a config change.
+ * @param {any} value - Value to stringify
+ * @returns {string} Stable string representation
+ */
+function stableStringifyForBotConfig(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringifyForBotConfig(v)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringifyForBotConfig(value[k])}`).join(',')}}`;
+    }
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? 'null' : serialized;
+}
+/**
+ * Normalize a raw bots.json entry for fingerprinting: drop volatile keys.
+ * @param {any} entry - Raw bot entry from bots.json
+ * @returns {any} Normalized plain object ({} when entry is missing)
+ */
+function normalizeBotEntryForFingerprint(entry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return {};
+    const out = {};
+    for (const key of Object.keys(entry)) {
+        if (BOT_CONFIG_FINGERPRINT_IGNORED_KEYS.includes(key))
+            continue;
+        out[key] = entry[key];
+    }
+    return out;
+}
+/**
+ * Build the full-entry fingerprint for one bot (stable across key order and
+ * comment/whitespace edits, since those never reach the parsed entry).
+ * @param {any} entry - Raw bot entry from bots.json
+ * @returns {string} Fingerprint ('' when entry is missing)
+ */
+function buildBotConfigFingerprint(entry) {
+    if (!entry || typeof entry !== 'object')
+        return '';
+    return stableStringifyForBotConfig(normalizeBotEntryForFingerprint(entry));
+}
+/**
+ * Plain-data deep clone (bots.json entries are JSON-parsed, always
+ * serializable; the fallback only guards exotic test doubles).
+ * Single helper replacing the previously triplicated inline clones.
+ * @param {any} value - Value to clone
+ * @returns {any} Deep clone (or the original when unserializable)
+ */
+function cloneJsonValue(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Merge the given entry keys into the live runtime (bot.config +
+ * manager.config) and refresh the derived weight base when included.
+ * Shared by the live bot-config check (allowlisted keys) — the full
+ * grid-resync path uses replaceBotConfigFromEntryPreservingRuntime below.
+ * Synchronous in-memory merge only: no chain I/O, no fill-lock (assignments
+ * are atomic; maintenance / targeted-reconcile ticks heal shortfalls/excess).
+ * @param {any} bot - DEXBot instance
+ * @param {any} entry - Raw bot entry from bots.json
+ * @param {string[]} keys - Entry keys to merge
+ * @returns {string[]} Merged key names
+ */
+function mergeBotConfigKeysIntoRuntime(bot, entry, keys) {
+    const applied = [];
+    if (!bot?.config || !entry || typeof entry !== 'object')
+        return applied;
+    for (const key of keys) {
+        // A deleted key applies as null (mirrors the former ?? null diff
+        // semantics) so the running config can never keep a stale value.
+        // Cloned twice: bot.config and manager.config must never alias the
+        // same nested object, or a future in-place mutation of one would
+        // silently corrupt the other.
+        const cloned = cloneJsonValue(entry[key] ?? null);
+        bot.config[key] = cloned;
+        if (bot.manager?.config) {
+            bot.manager.config[key] = cloneJsonValue(entry[key] ?? null);
+        }
+        if (key === 'weightDistribution') {
+            bot._baseWeightDistribution = cloned && typeof cloned === 'object' ? { ...cloned } : cloned;
+        }
+        applied.push(key);
+    }
+    return applied;
+}
+/**
+ * Full config replace preserving runtime identity (botKey/botIndex) and the
+ * constructor-resolved runtime settings (timing, gridLimits, feeParams,
+ * etc.). Shared single implementation for performGridResync (previously an
+ * inline block duplicating the merge/weights/refresh steps).
+ * @param {any} bot - DEXBot instance
+ * @param {any} updatedBot - Raw bot entry from bots.json
+ * @param {string} contextLabel - Label for the weights-refresh log context
+ */
+function replaceBotConfigFromEntryPreservingRuntime(bot, updatedBot, contextLabel) {
+    const oldKey = bot.config.botKey;
+    const oldIndex = bot.config.botIndex;
+    // 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 (bot.config[key] !== undefined) {
+            runtimeProps[key] = bot.config[key];
+        }
+    }
+    bot._log(`Reloaded configuration for bot '${bot.config.name}'`);
+    bot.config = { ...updatedBot, botKey: oldKey, botIndex: oldIndex, ...runtimeProps };
+    if (bot.manager?.config) {
+        bot.manager.config = { ...bot.manager.config, ...bot.config };
+    }
+    // bot.config is a new object now: re-point the credit runtime (its getter
+    // reads this.config) so the resync path can't leave it on the stale copy.
+    // The live-merge path mutates in place and never needs this.
+    if (bot._creditRuntime) {
+        bot._creditRuntime.config = bot.config;
+    }
+    bot._baseWeightDistribution = cloneWeightDistribution(updatedBot.weightDistribution, bot._baseWeightDistribution);
+    refreshDynamicWeightDistribution(bot, contextLabel);
+}
+/**
+ * Structural gate for live debtPolicy merges (mirrors the credit runtime's
+ * isEnabled gate plus the startup validator's required string fields in
+ * bot_settings.ts). Full numeric validation stays where it belongs:
+ * the `dexbot bot` editor at save time and per-offer at runtime.
+ * null/undefined (policy removal) is safe — it takes the disable path.
+ * @param {any} value - New debtPolicy value from bots.json
+ * @returns {boolean} True when safe to merge live
+ */
+function isDebtPolicyLiveApplySafe(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const lending = value.lending;
+    if (!Array.isArray(lending) || lending.length === 0)
+        return false;
+    return lending.every((item) => item && typeof item === 'object'
+        && typeof item.type === 'string' && item.type.length > 0
+        && typeof item.asset === 'string' && item.asset.length > 0
+        && typeof item.collateralAsset === 'string' && item.collateralAsset.length > 0);
+}
+/**
+ * Reconcile the credit runtime after a live debtPolicy merge: (re)create +
+ * load state when newly enabled, rebind the watchdog interval to the
+ * current runtime, stop the interval when disabled. loadState is a no-op on
+ * an already-loaded runtime and both maintenance entry points bail while
+ * disabled or in-flight, so this is safe on any tick (bot-level seams
+ * guarded for stripped test doubles).
+ * @param {any} bot - DEXBot instance
+ */
+async function reconcileCreditRuntimeAfterPolicyChange(bot) {
+    try {
+        if (typeof bot._setupCreditRuntime === 'function') {
+            await bot._setupCreditRuntime();
+        }
+    }
+    catch (err) {
+        bot._warn?.(`Credit runtime setup failed after debtPolicy change: ${getErrorMessage(err)}`);
+        return;
+    }
+    try {
+        if (bot._creditRuntime) {
+            if (typeof bot._setupCreditWatchdogInterval === 'function') {
+                bot._setupCreditWatchdogInterval();
+            }
+        }
+        else if (typeof bot._stopCreditWatchdogInterval === 'function') {
+            bot._stopCreditWatchdogInterval();
+        }
+    }
+    catch (err) {
+        bot._warn?.(`Credit watchdog reconcile failed after debtPolicy change: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Diff two normalized entries in a single pass over the key union.
+ * Replaces the former twin-loop diffLiveBotConfig +
+ * detectNonLiveBotConfigChanges pair.
+ * @param {any} oldNormalized - Previously seen normalized entry
+ * @param {any} newNormalized - New normalized entry
+ * @returns {{liveChanges: Array<{key: string, oldValue: any, newValue: any}>, otherKeys: string[]}} Split changes
+ */
+function diffBotConfigEntries(oldNormalized, newNormalized) {
+    const prev = oldNormalized && typeof oldNormalized === 'object' ? oldNormalized : {};
+    const next = newNormalized && typeof newNormalized === 'object' ? newNormalized : {};
+    const liveChanges = [];
+    const otherKeys = [];
+    for (const key of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+        const before = stableStringifyForBotConfig(prev[key] ?? null);
+        const after = stableStringifyForBotConfig(next[key] ?? null);
+        if (before === after)
+            continue;
+        if (BOT_LIVE_CONFIG_KEYS.includes(key)) {
+            liveChanges.push({ key, oldValue: prev[key] ?? null, newValue: next[key] ?? null });
+        }
+        else {
+            otherKeys.push(key);
+        }
+    }
+    return { liveChanges, otherKeys };
+}
+/**
+ * Check bots.json for this bot's entry and live-apply allowlisted keys
+ * (BOT_LIVE_CONFIG_KEYS; debtPolicy additionally reconciles the credit
+ * runtime, malformed debtPolicy is hinted instead of merged).
+ * Best-effort and idempotent: synchronous in-memory merge only, no chain
+ * I/O, no fill-lock (assignments are atomic; the existing maintenance /
+ * targeted-reconcile ticks heal shortfalls/excess on the next cycle).
+ * Geometry changes are NOT applied (need `dexbot reset <bot>`), identity
+ * changes are NOT applied (need restart) — on the steady-state path both
+ * produce a one-time hint per fingerprint (the fingerprint advances past
+ * hinted keys, malformed debtPolicy included, so a persistently-broken file
+ * warns once until the file changes again). The first-check baseline only
+ * converges the race-safe keys and stays silent on the rest: a geometry
+ * edit landing in the process-load → first-tick window is absorbed into
+ * the baseline with no hint. Corrupt/unreadable files and missing entries
+ * never touch the stored fingerprint (except the missing-entry hint
+ * throttle) so the next tick re-evaluates.
+ * @param {any} bot - DEXBot instance
+ * @param {string} [context='bots-config poll'] - Context label for logging
+ * @param {any} [preloadedSnapshot=null] - Reuse an already-loaded snapshot
+ * @returns {Promise<any>} Result with applied/liveChanges/otherKeys or skipped
+ */
+async function checkAndApplyBotConfigChanges(bot, context = 'bots-config poll', preloadedSnapshot = null) {
+    try {
+        if (!bot || !bot.config) {
+            return { skipped: true, reason: 'missing-config' };
+        }
+        const snapshot = preloadedSnapshot
+            ?? (typeof bot._loadBotsConfigSnapshot === 'function'
+                ? await bot._loadBotsConfigSnapshot()
+                : loadBotsConfigSnapshot());
+        if (!snapshot || snapshot.corrupt || snapshot.readError) {
+            return {
+                skipped: true,
+                reason: snapshot?.corrupt ? 'corrupt-config' : snapshot?.readError ? 'unreadable-config' : 'missing-snapshot',
+            };
+        }
+        const entry = findSnapshotBotForRuntimeConfig(snapshot, bot.config);
+        const botName = String(bot.config?.name || bot.config?.botKey || 'bot');
+        if (!entry) {
+            const missingMarker = `missing:${String(bot.config?.botKey || bot.config?.name || '')}`;
+            if (bot._lastBotConfigHintFingerprint !== missingMarker) {
+                bot._lastBotConfigHintFingerprint = missingMarker;
+                bot._warn?.(`bots.json no longer contains an active entry for '${botName}' during ${context}; ` +
+                    `roster changes need a stop/start.`);
+            }
+            return { skipped: true, reason: 'bot-not-found' };
+        }
+        const normalized = normalizeBotEntryForFingerprint(entry);
+        const fingerprint = stableStringifyForBotConfig(normalized);
+        if (bot._appliedBotConfigFingerprint === null || bot._appliedBotConfigFingerprint === undefined) {
+            bot._appliedBotConfigFingerprint = fingerprint;
+            bot._appliedBotConfigEntry = normalized;
+            // Startup race: the file may have changed between process config
+            // load and this first check. Converge the race-safe keys so the
+            // running bot can never sit on a value the file no longer
+            // contains. weightDistribution is excluded —
+            // refreshDynamicWeightDistribution owns the live value at runtime.
+            const racePrev = {};
+            for (const key of BOT_LIVE_CONFIG_KEYS) {
+                if (key === 'weightDistribution')
+                    continue;
+                racePrev[key] = bot.config?.[key];
+            }
+            const raceDiff = diffBotConfigEntries(racePrev, normalized);
+            // Same invariant as the steady-state path: a malformed debtPolicy
+            // never reaches the runtime (warn once; the next save re-evaluates).
+            const raceLive = raceDiff.liveChanges.filter((c) => c.key !== 'debtPolicy' || isDebtPolicyLiveApplySafe(c.newValue));
+            if (raceLive.length !== raceDiff.liveChanges.length) {
+                bot._warn?.(`bots.json debtPolicy for '${botName}' failed validation at startup check; ` +
+                    `keeping startup policy — fix the shape or run 'dexbot reset ${botName}'.`);
+            }
+            const raceApplied = mergeBotConfigKeysIntoRuntime(bot, entry, raceLive.map((c) => c.key));
+            if (raceApplied.includes('debtPolicy')) {
+                await reconcileCreditRuntimeAfterPolicyChange(bot);
+            }
+            if (raceApplied.length > 0) {
+                bot._log?.(`Picked up bots.json changes for '${botName}' at startup check (no restart needed): ${raceApplied.join(', ')}.`, 'info');
+            }
+            return { applied: raceApplied.length > 0, reason: 'baseline', fingerprint, liveChanges: raceApplied };
+        }
+        if (fingerprint === bot._appliedBotConfigFingerprint) {
+            return { applied: false, reason: 'unchanged', fingerprint };
+        }
+        const { liveChanges: rawLiveChanges, otherKeys: rawOtherKeys } = diffBotConfigEntries(bot._appliedBotConfigEntry, normalized);
+        // Malformed debtPolicy never reaches the runtime: hint reset/restart
+        // instead of merging garbage the credit cycle would choke on.
+        const liveChanges = rawLiveChanges.filter((c) => c.key !== 'debtPolicy' || isDebtPolicyLiveApplySafe(c.newValue));
+        const otherKeys = [...rawOtherKeys];
+        for (const c of rawLiveChanges) {
+            if (c.key === 'debtPolicy' && !isDebtPolicyLiveApplySafe(c.newValue) && !otherKeys.includes('debtPolicy')) {
+                otherKeys.push('debtPolicy');
+            }
+        }
+        const appliedKeys = mergeBotConfigKeysIntoRuntime(bot, entry, liveChanges.map((c) => c.key));
+        if (appliedKeys.includes('debtPolicy')) {
+            await reconcileCreditRuntimeAfterPolicyChange(bot);
+        }
+        if (appliedKeys.includes('weightDistribution')) {
+            // Same as the resync path: the file value is the base, the live
+            // effective weights (when whitelisted/ready) take precedence in
+            // bot/manager config immediately instead of next tick.
+            refreshDynamicWeightDistribution(bot, context);
+        }
+        bot._appliedBotConfigFingerprint = fingerprint;
+        bot._appliedBotConfigEntry = normalized;
+        if (liveChanges.length > 0) {
+            const summary = liveChanges
+                .map((c) => `${c.key} ${stableStringifyForBotConfig(c.oldValue)}->${stableStringifyForBotConfig(c.newValue)}`)
+                .join('; ');
+            bot._log?.(`Applied bots.json changes for '${botName}' live during ${context} (no restart needed): ${summary}. ` +
+                `Targeted maintenance will place missing / cancel excess orders.`, 'info');
+        }
+        if (otherKeys.length > 0) {
+            const shown = otherKeys.slice(0, 8).join(', ');
+            const suffix = otherKeys.length > 8 ? ` (+${otherKeys.length - 8} more)` : '';
+            bot._warn?.(`bots.json changed ${shown}${suffix} for '${botName}' during ${context}; ` +
+                `these were NOT applied live — run 'dexbot reset ${botName}' for grid geometry ` +
+                `or restart for market/account identity.`);
+        }
+        if (liveChanges.length === 0 && otherKeys.length === 0) {
+            bot._log?.(`Detected bots.json bookkeeping change for '${botName}' during ${context}; no tradable setting changed.`, 'debug');
+        }
+        return { applied: liveChanges.length > 0, liveChanges: liveChanges.map((c) => c.key), otherKeys, fingerprint };
+    }
+    catch (err) {
+        try {
+            bot?._warn?.(`Bot-config live check failed during ${context}: ${getErrorMessage(err)}`);
+        }
+        catch { /* logging must never break the tick */ }
+        return { skipped: true, reason: 'error', error: getErrorMessage(err) };
+    }
+}
 function countLiveGridOrders(manager, type) {
     if (!manager)
         return 0;
@@ -156,7 +525,86 @@ function countLiveGridOrders(manager, type) {
 }
 function getTargetActiveOrders(config, side) {
     const configured = Number(config?.activeOrders?.[side]);
-    return Math.max(0, Number.isFinite(configured) ? configured : 1);
+    // Reserve ladder rests live on-chain: countLiveGridOrders sees window +
+    // edge orders, so the shortfall target must include reserves too —
+    // otherwise live reserves mask window shortfalls and a filled/cancelled
+    // reserve order never triggers targeted reconciliation.
+    const reserves = resolveReserveCount(config, side);
+    return Math.max(0, Number.isFinite(configured) ? configured : 1) + reserves;
+}
+/**
+ * Count live on-chain reserve orders for one side (issue #27 follow-up).
+ *
+ * The window shortfall check above compares live window+reserves against
+ * window+reserves, so a pre-existing window surplus masks a reserve deficit
+ * (e.g. target 6+2=8 vs 12 live after reserveOrders 0→2: no shortfall, no
+ * sync, zero reserve placements). Reserves get their own independent reason
+ * below — the mirror of the masking case getTargetActiveOrders handles.
+ *
+ * Classification reuses the single source of truth (reserveEdgeIdSet +
+ * resolveLiveReserveEdgeAnchorPrice, same anchor the placement pickers use)
+ * over the full master grid, intersected with live ACTIVE/PARTIAL orderIds
+ * (same live definition as countLiveGridOrders). The edge pick excludes the
+ * window (liveWindowIdSet — the same exclusion every placement picker
+ * applies): window + edge are additive in targets/fees/hold-back, but
+ * without the exclusion a window that reaches the grid edge (keep-low
+ * window = bottom slots = floor edge) makes the edge pick land on window
+ * members and the count reads N/N with zero dedicated reserves, so the
+ * deficit never fires (issue #27 follow-up).
+ * @param {any} manager - OrderManager
+ * @param {any} config - Bot configuration (reserve count source)
+ * @param {any} type - ORDER_TYPES.BUY or ORDER_TYPES.SELL
+ * @returns {number|null} Live reserve count, or null when unclassifiable
+ */
+function countLiveReserveOrders(manager, config, type) {
+    try {
+        const side = type === ORDER_TYPES.SELL ? 'sell' : 'buy';
+        const required = resolveReserveCount(config, side);
+        if (!(required > 0))
+            return 0;
+        if (!manager)
+            return null;
+        // Full master grid only: classifying from live-only indexed lookups
+        // would pick the "edge" of the live subset, not the grid edge, and
+        // mis-fire on stripped test doubles. Fail closed (null) without it.
+        if (!manager.orders || typeof manager.orders.values !== 'function')
+            return null;
+        const allSlots = Array.from(manager.orders.values());
+        if (allSlots.length === 0)
+            return null;
+        const anchor = resolveLiveReserveEdgeAnchorPrice(manager, side);
+        // Fail open on unknown window geometry (null): without a boundary the
+        // pickers cannot place reserves either, so keep the previous
+        // (exclusion-free) classification instead of guessing.
+        const windowIds = liveWindowIdSet(manager, type);
+        const reserveIds = reserveEdgeIdSet(allSlots, config, type, anchor, windowIds);
+        if (!reserveIds || reserveIds.size === 0)
+            return 0;
+        const liveIds = new Set();
+        if (typeof manager.getOrdersByTypeAndState === 'function') {
+            for (const state of [ORDER_STATES.ACTIVE, ORDER_STATES.PARTIAL]) {
+                for (const o of manager.getOrdersByTypeAndState(type, state) || []) {
+                    if (o?.id != null && o?.orderId)
+                        liveIds.add(String(o.id));
+                }
+            }
+        }
+        else {
+            for (const s of allSlots) {
+                if (s?.id != null && s?.orderId)
+                    liveIds.add(String(s.id));
+            }
+        }
+        let live = 0;
+        for (const id of reserveIds) {
+            if (liveIds.has(String(id)))
+                live++;
+        }
+        return live;
+    }
+    catch {
+        return null;
+    }
 }
 function _hasBudgetForSide(manager, config, side) {
     try {
@@ -192,6 +640,21 @@ function getTargetedSyncReason(bot) {
             shortfalls.push(`sell ${liveSell}/${targetSell}`);
         }
     }
+    // Reserve deficit is independent of window surplus: a bot carrying extra
+    // rail/stranded orders can sit above target while its reserve edge is
+    // empty (live-applied reserveOrders 0→N, filled/cancelled reserve).
+    // Without this, placement waits for fills or the 4h fetch (issue #27).
+    for (const [type, side] of [[ORDER_TYPES.BUY, 'buy'], [ORDER_TYPES.SELL, 'sell']]) {
+        const required = resolveReserveCount(bot.config, side);
+        if (!(required > 0))
+            continue;
+        const liveReserves = countLiveReserveOrders(bot.manager, bot.config, type);
+        if (liveReserves !== null && liveReserves < required) {
+            if (_hasBudgetForSide(bot.manager, bot.config, side)) {
+                shortfalls.push(`${side} reserves ${liveReserves}/${required}`);
+            }
+        }
+    }
     const drift = bot.manager.checkFundDriftAfterFills?.();
     if (drift && drift.isValid === false) {
         return { reason: `fund drift: ${drift.reason}`, targetBuy, targetSell, liveBuy, liveSell, drift };
@@ -357,13 +820,35 @@ async function syncMarketAdapterOnPeriodicConfigCheck(bot, context = 'periodic')
     if (typeof bot._syncMarketAdapterHook === 'function') {
         return await bot._syncMarketAdapterHook(context);
     }
+    // Single bots.json read shared by the live bot-config check and the
+    // adapter drive below (one read per tick, not two). Throwing reads
+    // (transient I/O) behave like corrupt: skip everything, keep stored
+    // fingerprints, retry next tick.
+    let snapshot = null;
+    try {
+        snapshot = typeof bot._loadBotsConfigSnapshot === 'function'
+            ? await bot._loadBotsConfigSnapshot()
+            : loadBotsConfigSnapshot();
+    }
+    catch (err) {
+        bot._warn(`Ignoring unreadable bots.json during ${context}; keeping previous market adapter state.`);
+        return { skipped: true, reason: 'unreadable-config' };
+    }
+    // Live bot-config check runs on EVERY path (including wrapper-owned):
+    // no adapter driving, best-effort. It live-applies allowlisted keys
+    // (BOT_LIVE_CONFIG_KEYS) and hints
+    // reset/restart for everything else (Issue #27 follow-up).
+    try {
+        await checkAndApplyBotConfigChanges(bot, context, snapshot);
+    }
+    catch { /* checkAndApply never throws; belt-and-suspenders */ }
     // Centralized ownership: in monolithic mode the unlock wrapper watchdog
-    // (shared 1min tick) is the sole market-adapter spawner. A per-bot sync here would
-    // re-read bots.json and re-drive the adapter N times (once per bot) and
-    // fight the wrapper over the adapter child, so bots skip it entirely and
-    // act as pure adapter-output consumers. Wrapper-less modes (dexbot test
-    // one-shot, isolated supervisor, PM2) keep the in-bot fallback below.
-    // Checked before any file I/O so the skip also removes the duplicate read.
+    // (shared 1min tick) is the sole market-adapter spawner. A per-bot drive here would
+    // re-drive the adapter N times (once per bot) and fight the wrapper over
+    // the adapter child, so bots skip the adapter drive entirely and act as
+    // pure adapter-output consumers. The live bot-config check above still
+    // ran. Wrapper-less modes (dexbot test one-shot, isolated supervisor,
+    // PM2) keep the in-bot fallback below.
     if (!isPm2Runtime() && isWrapperAdapterOwner()) {
         return { skipped: true, reason: 'wrapper-owned' };
     }
@@ -372,9 +857,6 @@ async function syncMarketAdapterOnPeriodicConfigCheck(bot, context = 'periodic')
     }
     bot._marketAdapterWatchdogInFlight = true;
     try {
-        const snapshot = typeof bot._loadBotsConfigSnapshot === 'function'
-            ? await bot._loadBotsConfigSnapshot()
-            : loadBotsConfigSnapshot();
         // Corrupt/unreadable bots.json must not move the adapter: previously
         // the parse/read throw aborted the check and left the adapter alone.
         // Keep that behavior by skipping the sync without touching the stored
@@ -744,22 +1226,7 @@ function performGridResync(bot, options = {}) {
                 const myName = self.config.name;
                 const updatedBot = allBotsConfig.find((b) => isSameBotName(b.name, myName));
                 if (updatedBot) {
-                    self._log(`Reloaded configuration for bot '${myName}'`);
-                    const oldKey = self.config.botKey;
-                    const oldIndex = self.config.botIndex;
-                    // 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');
+                    replaceBotConfigFromEntryPreservingRuntime(self, updatedBot, 'grid resync');
                 }
             }
             catch (e) {
@@ -977,6 +1444,29 @@ async function performPeriodicGridChecks(bot) {
     else {
         await runGridMaintenance(bot, 'periodic');
     }
+    logDeferredHoldSummary(bot);
+}
+/**
+ * Summarize deliberate deferred holds once per count change. The per-order
+ * sync logs report each hold when it first appears; this surfaces the running
+ * total (funds stay locked until an operator clears them) without re-logging
+ * the same count every tick.
+ *
+ * @param {import('./dexbot_class.js').DEXBot} bot
+ */
+function logDeferredHoldSummary(bot) {
+    const unmatched = Array.isArray(bot.manager?._lastUnmatchedChainOrders)
+        ? bot.manager._lastUnmatchedChainOrders
+        : [];
+    const held = unmatched.filter((u) => isNonBlockingUnmatchedOrder(u)).length;
+    if (held === 0) {
+        bot._lastHeldChainOrderCount = 0;
+        return;
+    }
+    if (held === bot._lastHeldChainOrderCount)
+        return;
+    bot._lastHeldChainOrderCount = held;
+    bot._log?.(`[HOLD] ${held} deferred chain order(s) held outside the active pipeline (funds stay locked until cleared)`, 'warn');
 }
 /**
  * Check if the continuous open-orders sync loop is enabled.
@@ -1217,17 +1707,15 @@ function stopBlockchainFetchInterval(bot) {
     }
 }
 /**
- * Set up the periodic bots.json fingerprint poll interval.
- * Fallback config-change detector for wrapper-less modes (dexbot test
- * one-shot, isolated supervisor, PM2): decoupled from the heavy blockchain
- * fetch interval (default 240min) so config changes are visible within
- * BOTS_CONFIG_POLL_INTERVAL_MS (default 1min, shared with the wrapper
- * watchdog interval).
- * In monolithic mode the unlock wrapper watchdog already polls bots.json
- * on the same shared interval as the sole adapter owner, so no per-bot poll
- * is created here.
- * Uses the shared fingerprint via syncMarketAdapterOnPeriodicConfigCheck so
- * the market adapter start/stop logic stays in one place.
+ * Set up the periodic bots.json poll interval.
+ * Runs in ALL modes (including wrapper-owned monolithic): the tick drives
+ * syncMarketAdapterOnPeriodicConfigCheck, which always runs the live
+ * bot-config check (allowlisted keys applied without restart, Issue #27
+ * follow-up) and additionally drives the market adapter only in
+ * wrapper-less modes (dexbot test one-shot, isolated supervisor, PM2).
+ * Decoupled from the heavy blockchain fetch interval (default 240min) so
+ * config changes are visible within BOTS_CONFIG_POLL_INTERVAL_MS
+ * (default 1min, shared with the wrapper watchdog interval).
  * @param {import('./dexbot_class.js').DEXBot} bot
  */
 function setupBotsConfigPollInterval(bot) {
@@ -1237,13 +1725,14 @@ function setupBotsConfigPollInterval(bot) {
         intervalMs = Number(TIMING.BOTS_CONFIG_POLL_INTERVAL_MS);
     }
     if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
-        bot._log(`Bots-config poll interval disabled (value: ${intervalMs}). Fingerprint changes will only be seen on blockchain fetch ticks.`);
-        return;
-    }
-    if (!isPm2Runtime() && isWrapperAdapterOwner()) {
-        bot._log('Bots-config poll disabled (market adapter owned by unlock wrapper).');
+        bot._log(`Bots-config poll interval disabled (value: ${intervalMs}). Adapter and live bot-config changes will only be seen on blockchain fetch ticks.`);
         return;
     }
+    // NOTE: no wrapper-owned early return here on purpose. The adapter drive
+    // inside syncMarketAdapterOnPeriodicConfigCheck still skips when the
+    // wrapper owns it, but the live bot-config check at the top of that
+    // function must run for every bot (otherwise monolithic bots would never
+    // pick up bots.json edits until the 240min blockchain fetch tick).
     // Ensure the fingerprint exists before the first interval fires.
     // setupBlockchainFetchInterval already fires syncMarketAdapterOnPeriodicConfigCheck
     // at startup, so this is a fallback for bots that never run the blockchain interval
@@ -1280,7 +1769,7 @@ function setupBotsConfigPollInterval(bot) {
     if (typeof bot._botsConfigPollInterval.unref === 'function') {
         bot._botsConfigPollInterval.unref();
     }
-    bot._log(`Started bots-config poll interval: every ${Math.round(intervalMs / 1000)}s (fingerprint check)`);
+    bot._log(`Started bots-config poll interval: every ${Math.round(intervalMs / 1000)}s (adapter fingerprint + live bot-config check)`);
 }
 /**
  * Stop the periodic bots.json fingerprint poll interval.
@@ -1584,7 +2073,9 @@ async function executeMaintenanceLogic(bot, context) {
             if (divergence.needsUpdate) {
                 const hasRmsDivergence = !!(divergence.buy.rms || divergence.sell.rms);
                 if (divergence.buy.ratio || divergence.sell.ratio) {
-                    bot._log(`Grid update triggered by funds during ${context} (buy: ${divergence.buy.ratio}, sell: ${divergence.sell.ratio})`);
+                    const buyDir = divergence.buy.shrink ? '/shrink' : '';
+                    const sellDir = divergence.sell.shrink ? '/shrink' : '';
+                    bot._log(`Grid update triggered by funds during ${context} (buy: ${divergence.buy.ratio}${buyDir}, sell: ${divergence.sell.ratio}${sellDir})`);
                 }
                 if (hasRmsDivergence) {
                     bot._log(`Grid update triggered by structural divergence during ${context}: buy=${Format.formatPrice6(divergence.buy.metric)}, sell=${Format.formatPrice6(divergence.sell.metric)}`);
@@ -2032,6 +2523,7 @@ function drainFillQueueAfterPipelineClear(bot) {
         if (!bot._incomingFillQueue || bot._incomingFillQueue.length === 0)
             return;
         bot._log(`[FILL-QUEUE] Pipeline cleared; draining ${bot._incomingFillQueue.length} deferred fill(s).`, 'info');
+        bot._deferredFillsPending = true;
         scheduleFillConsumerRestartFn(bot, chainOrders);
     }
     catch { }
@@ -2239,6 +2731,14 @@ function markGridActivity(bot, reason = 'activity') {
  */
 function getMetrics(bot) {
     bot.manager?._cleanExpiredLocks?.();
+    const unmatched = Array.isArray(bot.manager?._lastUnmatchedChainOrders)
+        ? bot.manager._lastUnmatchedChainOrders
+        : [];
+    // Deliberate holds (reason suffixed `-deferred`) never block the pipeline,
+    // but they DO lock funds until an operator clears them. Surface the split
+    // so the permanent holds are visible in status/metrics instead of only in
+    // per-order sync logs.
+    const heldUnmatched = unmatched.filter((u) => isNonBlockingUnmatchedOrder(u));
     return {
         ...bot._metrics,
         queueDepth: bot._incomingFillQueue.length,
@@ -2246,7 +2746,10 @@ function getMetrics(bot) {
         divergenceLockActive: bot.manager?._divergenceLock?.isLocked() || false,
         shadowLocksActive: bot.manager?.shadowOrderIds?.size || 0,
         recoveryExhaustedAt: bot.manager?._recoveryExhaustedAt || null,
-        recentFillsTracked: bot._recentlyProcessedFills.size
+        recentFillsTracked: bot._recentlyProcessedFills.size,
+        unmatchedChainOrders: unmatched.length,
+        heldChainOrders: heldUnmatched.length,
+        blockingChainOrders: unmatched.length - heldUnmatched.length
     };
 }
 /**
@@ -2321,10 +2824,12 @@ async function syncOpenOrdersAndProcessFillsImpl(bot, tag) {
         return { syncResult: null, aborted: true, hasUnmatched: -1, openOrders: null };
     }
 }
-export { loadBotsConfigSnapshot, isWrapperAdapterOwner, refreshDynamicWeightDistribution, performGridResync, updateBotGridResetMetadata, handlePendingTriggerReset, setupTriggerFileDetection, performPeriodicGridChecks, isOpenOrdersSyncLoopEnabled, startOpenOrdersSyncLoop, stopOpenOrdersSyncLoop, setupBlockchainFetchInterval, stopBlockchainFetchInterval, setupBotsConfigPollInterval, stopBotsConfigPollInterval, executeMaintenanceLogic, cancelDustOrders, isOrderDoesNotExistError, runGridMaintenance, stopMarketAdapterPm2, releaseMarketAdapterRuntime, syncMarketAdapterOnPeriodicConfigCheck, findSnapshotBotForRuntimeConfig, runtimeConfigNeedsMarketAdapter, usesAmaGridPrice, checkBtsBalanceAndAcquire, acquireBts, runDustHealthCheck, setupDustHealthCheckInterval, requestGridReset, wireStructuralGridResyncRequest, getPipelineSignals, markGridActivity, getMetrics, syncOpenOrdersAndProcessFills };
+export { loadBotsConfigSnapshot, isWrapperAdapterOwner, checkAndApplyBotConfigChanges, buildBotConfigFingerprint, refreshDynamicWeightDistribution, performGridResync, updateBotGridResetMetadata, handlePendingTriggerReset, setupTriggerFileDetection, performPeriodicGridChecks, isOpenOrdersSyncLoopEnabled, startOpenOrdersSyncLoop, stopOpenOrdersSyncLoop, setupBlockchainFetchInterval, stopBlockchainFetchInterval, setupBotsConfigPollInterval, stopBotsConfigPollInterval, executeMaintenanceLogic, getTargetedSyncReason, countLiveReserveOrders, maybeRunTargetedDriftReconciliation, cancelDustOrders, isOrderDoesNotExistError, runGridMaintenance, stopMarketAdapterPm2, releaseMarketAdapterRuntime, syncMarketAdapterOnPeriodicConfigCheck, findSnapshotBotForRuntimeConfig, runtimeConfigNeedsMarketAdapter, usesAmaGridPrice, checkBtsBalanceAndAcquire, acquireBts, runDustHealthCheck, setupDustHealthCheckInterval, requestGridReset, wireStructuralGridResyncRequest, getPipelineSignals, markGridActivity, getMetrics, syncOpenOrdersAndProcessFills };
 export default {
     loadBotsConfigSnapshot,
     isWrapperAdapterOwner,
+    checkAndApplyBotConfigChanges,
+    buildBotConfigFingerprint,
     refreshDynamicWeightDistribution,
     performGridResync,
     updateBotGridResetMetadata,
@@ -2339,6 +2844,9 @@ export default {
     setupBotsConfigPollInterval,
     stopBotsConfigPollInterval,
     executeMaintenanceLogic,
+    getTargetedSyncReason,
+    countLiveReserveOrders,
+    maybeRunTargetedDriftReconciliation,
     cancelDustOrders,
     isOrderDoesNotExistError,
     runGridMaintenance,