dexbot 1.4.25 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.1] - 2026-09-06 - Gap-Evacuation Guard Allowance & Rail-Typed Holes
+
+### 2026-09-05
+
+- **Fix(sync)**: re-type SPREAD slots before chain-order adoption and honor the apply result — `adoptChainOrderIntoSlot` re-types the placeholder to the chain order's side before activation/precision work, returns a boolean, and callers only record bookkeeping on success; rejected adoptions land in unmatched orders and queue a cancel-only correction so the chain order cannot dangle untracked (`modules/order/sync_engine.ts`).
+- **Fix(accounting)**: rebuild tracked funds from chain during state recovery — verify the balance fetch actually refreshed (`_lastFetchedAt` advanced) before trusting balances and defer the attempt otherwise; when drift persists after sync, `_recalibrateTrackedFundsFromChain` rebuilds the tracked commitment from the fresh chain read (matched slots forced to chain size, fully-consumed and stale-absent slots virtualized under the same recent-commit lag guards as the sync orphan pass, free balances never derived from totals), then re-runs `recalculateFunds` and re-checks drift (`modules/order/accounting.ts`; `tests/test_accounting_logic.ts`, `tests/test_resync_invariants.ts` stubs now simulate a refreshing snapshot).
+- **Fix(cow)**: bit-identical same-price duplicate guard for CREATE slots — new `validateCreateTargetSlots` layer 5 keyed by side + blockchain-int price (`floatToBlockchainInt`, asset-aware with float fallback): first target per price wins, later duplicates reported as `same_batch_price_duplicate` and skipped by the caller; bit-exact by design so adjacent grid levels can never false-positive the way the removed tolerance layer did (`modules/order/utils/validate.ts`, `tests/test_validate_create_target_slots.ts`).
+- **Docs**: record the kept last-fill-guard pivot semantics in the guard's doc comment — pivot is the latest fill of either side and never expires; last sold level floors new sells, buy fills pull the pivot down and re-open the sell side, buy-below-sell is never gated (`modules/dexbot_cow_runtime.ts`).
+
+- **Fix(guard)**: allow violation-reducing gap-evacuation rotations past the last-fill guard — new pure `isEvacuationRotationAllowed(oldPrice, oldSize, newPrice, newSize, type, precision?)` in `modules/order/utils/math.ts` (bit-exact blockchain-int size compare, no float epsilon; outward repricing only; rail types only); COW rotation guard honors `origin='gap-evacuation'` on UPDATE actions only via the frozen plan-build B-stamp (`evacBoundary`/`evacGapSlots` stamped in `buildActionsFromPlan`, `reconcileGrid.pairRotations`, `optimizeRebalanceActions`) with fail-closed live-probe fallback (master-grid source read before rotation pre-application); lying "no origin bypass" comments rewritten (`modules/dexbot_cow_runtime.ts`, `modules/order/utils/validate.ts`, new `tests/test_gap_evacuation.ts` EVAC-001..004/009/010).
+- **Fix(holes)**: keep rail-typed VIRTUAL holes across fill/rotation/load cycles — new `toRailHolePlaceholder` (rail type + booked size preserved) used by COW plan pre-apply (`buildCowResultFromPlan`), divergence-COW surplus cancel (`modules/order/utils/system.ts`), and fill-consumed rail slots (`modules/order/strategy.ts`); load-time retype (`modules/order/grid.ts`) and `assignGridRoles` type empty slots by slot-index geometry (in-rail stays BUY/SELL, only true band slots are SPREAD; unparseable ids stay SPREAD); `validateOrder` documents rail-hole preservation; expect a one-time `[GRID-TYPE-CORRECT]` backfill spike on first load of legacy grids (`tests/test_gap_evacuation.ts` EVAC-006/011; `tests/test_grid_bloat.ts` and `tests/test_boundary_restore_validation.ts` updated to the rail-hole contract).
+- **Feat(evac)**: geometry-only gap-evacuation detection + per-slot streak counter — new `detectGapEvacuationCandidates` (slot idx vs frozen boundary/gapSlots, never stored type) and `updateGapEvacuationStreaks` (`manager._gapEvacStreaks`, persisted in the grid snapshot via `storeMasterGrid`/`persistGridSnapshot` and restored on startup/recovery with pruning to loaded slots; cancel markers stay in-memory by design) ticked per `reconcileGrid` plan with `[GAP-EVAC]` warn on stuck slots; new `GAP_EVACUATION_STREAK_THRESHOLD` (2) in `GRID_LIMITS` (`modules/order/utils/order.ts`, `modules/order/manager.ts`, `modules/account_orders.ts`, `modules/order/utils/system.ts`, `modules/dexbot_startup_runtime.ts`, `modules/dexbot_state_recovery.ts`, `modules/constants.ts`, `tests/test_gap_evacuation.ts` EVAC-007/008, `tests/test_gap_evac_persistence.ts` GEP-1..4).
+- **Feat(evac-teeth)**: cancel-only evacuation for orders that stay stranded in the gap band — `evacReady` now propagates out of the COW engine on both success and aborted plans, and the manager queues a correction per stuck slot at `GAP_EVACUATION_CANCEL_THRESHOLD` (3, one warn cycle after the streak threshold) via `_processGapEvacuationTeeth`: re-verifies CURRENT committed geometry + live slot ownership, queues once per slot (`_gapEvacCancelQueued`, marker released when the slot resolves), and uses surplus semantics so the runner cancels the chain order and settles the slot back to a SPREAD placeholder — no re-placement, fee-light (`modules/order/manager.ts`, `modules/constants.ts`, `tests/test_gap_evacuation.ts` EVAC-012..015).
+- **Diag(sync)**: orphan-adoption remap log carries slot geometry (idx/boundary/gap/sellStart/band-vs-rail) so the next re-map incident attributes the path without chain archaeology (`modules/order/sync_engine.ts`).
+- **Fix(tests)**: stub-class hardening for cold-guard batch-summary interference — UNC-015/015c assert on the full warn sequence instead of last-wins capture; `test_resync_invariants` case-4 fetch stub guarantees `_lastFetchedAt` advancement past same-ms collisions (production behavior unchanged; `tests/test_uncertain_broadcast.ts`, `tests/test_resync_invariants.ts`).
+- **Fix(accounting)**: guard the `updateOptimisticFreeBalance` debug line against an unresolvable order side — `formatSizeByOrderType` throws on unknown precision, so a debug-only log could crash the accounting flow; the line now falls back to raw numbers when the side is not BUY/SELL. Repairs the long-standing `test_scaled_spread_correction` Scenario B failure (pre-existing fixture crash since 1.5.0); full suite is green again (`modules/order/accounting.ts`).
+
+### 2026-09-06
+
+- **Feat(reconcile)**: refill rail levels vacated by startup re-map (vacate+create atomic) — `_reconcileStartupSide` records, per PROCEEDING update, whether the vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side and queues a refill CREATE in the same plan (`source startupVacatedRailRefill`); skipped updates (insufficient balance) vacate nothing, ghost prices (lattice moved) and in-band slots (evacuation/adoption paths own them) are skipped, as are slots already desired for activation (no double-place); refill targets require VIRTUAL state with no `orderId` (CANCELED slots and phantom VIRTUAL-with-orderId excluded) (`modules/order/grid_reconcile_internal.ts`, `tests/test_vacated_rail_refill.ts` VRR-1..7).
+- **Feat(evac)**: persist gap-evacuation streaks across restarts — `storeMasterGrid` accepts `gapEvacStreaks` (sanitized: finite positive counts only; explicit empty map clears the stored entry, `undefined` is a no-op for backward-compatible callers), `persistGridSnapshot` forwards the manager's streak map, `loadGapEvacStreaks` mirrors the other snapshot loaders, and `restoreGapEvacStreaks` (pruned to loaded slots) is wired into the startup active-session path and the recovery full-grid reload (`modules/account_orders.ts`, `modules/order/utils/system.ts`, `modules/dexbot_startup_runtime.ts`, `modules/dexbot_state_recovery.ts`, `tests/test_gap_evac_persistence.ts` GEP-1..4).
+- **Test**: incident-replay integration suite for gap-evacuation acceptance — with boundary 141 / gap 4 / increment 0.3% and three sell actives stranded in the band, the pipeline must plan exactly three stamped evacuation rotations, the plain last-fill guard must veto all three, both bypass routes (frozen B-stamp and live probe) must allow them, and the real pre-apply + working-grid commit must end with the band empty and a visible spread of ~1.5% (REP-001..004; `tests/test_incident_replay.ts`).
+- **Fix(guard)**: harden gap-evacuation stamping and execution re-verification — new exported `isEvacuationStampStillValid` re-verifies B-stamped evacuation UPDATEs against live committed geometry at execution (stale stamps downgrade to the unstamped live probe, which itself now requires valid live evacuation geometry); plan-level `withOrigin` routes gap-evacuation rotations through the real `stampGapEvacuationRotation` (geometry + bit-exact non-growing size with side precision + outward repricing must prove, refusals strip the origin, sourceless rotations stay unstamped, gap-plan CREATEs no longer carry a dead origin); stamp and live probe share bit-exact blockchain-int size semantics via threaded manager assets (`modules/dexbot_cow_runtime.ts`, `modules/order/utils/validate.ts`, `modules/order/manager.ts`, `modules/order/utils/system.ts`, `tests/test_gap_evacuation.ts` EVAC-016..019).
+- **Fix(sync)**: legacy fallback adoption parity — the legacy adoption branch now captures `_applyOrderUpdate`'s result and on rejection queues an adoption-rejected cancelOnly correction (mirroring the genesis branch) with bookkeeping only after a successful apply (`modules/order/sync_engine.ts`).
+- **Fix(cow)**: bit-exact same-batch price duplicate key — the layer-5 duplicate guard keys on `floatToBlockchainInt(price, sidePrecision)` when assets context exists (float fallback preserved for asset-less callers) so distinct prices quantizing to the same on-chain int no longer escape (`modules/order/utils/validate.ts`, `tests/test_validate_create_target_slots.ts`).
+
+## [1.5.0] - 2026-09-05 - Credit Overview & Whitelist-Scoped CR, TradingView Shortcut, Reload Command, Guard & Rotation Hardening
+
+### 2026-09-02
+
+- **Fix(editor)**: bold Mountain weight in selector display (`modules/account_bots.ts`).
+
+### 2026-09-03
+
+- **Feat(cli)**: add `dexbot credit` live per-bot debt overview and centralize CLI color palette — new `scripts/analyze-credit.ts` (wired as `dexbot credit [<bot>]`) queries live `get_margin_positions` + paginated `get_credit_deals_by_borrower` per preferredAccount and prints summed debt/collateral per asset per bot (lending-asset filtered, shared accounts tagged, chain chatter muted, inclusive-pagination overlap dropped to avoid double-counting); new `modules/cli_colors.ts` (`CLI_COLORS`) is the single source of truth for every ANSI shade repo-wide with no visual change (`scripts/analyze-credit.ts`, `dexbot.ts`, `modules/cli_colors.ts`, `README.md`, `docs/WORKFLOW.md`, `tests/test_analyze_credit.ts`).
+
+### 2026-09-04
+
+- **Feat(credit)**: whitelist-scoped CR reporting and shared credit-pricing math — new browser-safe `modules/credit_pricing.ts` holds the canonical math (collateral-map normalization, core/legacy-reversed orientation, offer conversion rates, per-deal and value-weighted average CR, fee helpers) with `credit_runtime.ts` delegating to it (conversion-rate fallback extended offer → pool-derived → universal market price incl. BTS-bridge hops); analyzer per-pair `Curr. CR` and per-bot `Avar. CR` are now scoped to whitelisted `debtPolicy.lending` pairs priced on the current offer, color-coded vs `maxCollateralRatio`, with `Excluded` split by reason and uncapped offer pagination; new `derivePriceViaBridges`/`derivePriceWithBridges` in `modules/order/utils/system.ts` (LP legs bridge only on opt-in) (`modules/credit_pricing.ts`, `modules/credit_runtime.ts`, `modules/order/utils/system.ts`, new `tests/test_credit_pricing.ts`, `tests/test_price_bridges.ts`, `tests/test_credit_conversion_fallback.ts`).
+- **Feat(cli)**: add `dexbot reload` that leaves the credential daemon untouched — mirrors `restart` on every runtime surface (unlock `reload-all` recycles bots + market adapter via SIGUSR2 skipping the daemon re-unlock block, supervisor `reload`/`reload-all`, `pm2 restart` with no `ensureCredentialDaemon`, `reload dexbot-cred` rejected) so bot/adapter recycling no longer costs a password prompt (`unlock.ts`, `modules/launcher/bot_supervisor.ts`, `modules/launcher/launch_modes.ts`, `modules/launcher/monolithic_runtime.ts`, `pm2.ts`, `dexbot.ts`, `README.md`, `docs/WORKFLOW.md`).
+- **Fix(identity)**: enforce case-insensitive bot-name identity across lookups — new `isSameBotName` in `modules/utils/sanitize_key.ts` (sanitized compare with blank-input guard) used by bot_settings, dexbot, unlock, bot, pm2, claw launcher/profiles/credit adapter, maintenance runtime, market-adapter inputs and helper scripts; PM2 stop/delete/restart/reload resolve to the canonical stored name, example pair-derived bot names in comments/help/fixtures replaced with a generic placeholder (published changelog history untouched).
+- **Fix(update)**: run `npm install` only when dependencies actually changed — new `needsDepsInstall(preUpdateHead)` gate in `scripts/update.ts` (install only when node_modules missing/incomplete, manifests changed since pre-update commit, or manifests worktree-dirty; fail-open on git errors) plus a `lockRegenerated` double-install guard (`scripts/update.ts`).
+- **Fix(adapter)**: centralize market-adapter ownership in unlock wrapper on one 1min interval — new `modules/launcher/adapter_requirement.ts` (semantic name:gridPrice fingerprint, corrupt/unreadable bots.json reported not thrown); wrapper exports `DEXBOT_ADAPTER_OWNER=wrapper` so supervised bots skip adapter sync and create no poll timer (wrapper-less modes keep the in-bot fallback); `TIMING.BOTS_CONFIG_POLL_INTERVAL_MS` now 60s shared with the watchdog interval; fixes `''`-fingerprint false-change and corrupt-skip regressions (`modules/launcher/adapter_requirement.ts`, `unlock.ts`, `modules/constants.ts`, `modules/launcher/*`, `modules/dexbot_class.ts`).
+- **Feat(accounts)**: cache bot account IDs in bots.json for offline resolution — byte-preserving in-place `accountId` patch in `analysis/bot_key_utils.ts` (comment/string-aware scanner, re-parse assert, atomic write, full-rewrite fallback) with `persistBotAccountId`/`getStoredBotAccountId`/`findBotKeyByAccountRef`; new `analysis/resolve_bot_accounts.ts` batch backfill CLI (`npm run analysis:resolve-accounts`, `--dry-run`/`--refresh`/`--bot-key`/`--json`); editor stamps IDs via `ensureBotAccountId`, analysis tools and `test-credit-renewal` prefer the cache with `--refresh-account` re-verify; process-wide console floor (`setGlobalConsoleLevel`) silences node-init chatter during supervised lookups (`analysis/bot_key_utils.ts`, `analysis/resolve_bot_accounts.ts`, `modules/account_bots.ts`, `modules/order/logger.ts`, `modules/bitshares_client.ts`, `tests/test_bot_account_id.js`, `tests/test_logger_console_floor.js`).
+- **Fix(guard)**: close stale-pivot race in last-fill guard and harden spread correction — `refreshLastFillPivotFromQueue()` peeks the incoming fill queue before every COW guard check (CREATE, rotation UPDATE, fallback CREATE) and `recordLastFilledPrices()` now runs per chunk so later broadcast chunks gate on the true latest fill; per-action plan-origin stamping keeps spread-correction CREATE bypass while rotation UPDATEs never bypass; `determineOrderSideByFunds()` returns null instead of cross-asset raw-unit compare when priceless with both sides funded; spread check defers on post-gate fills with funds recalc before side decision; batch-level LAST-FILL-GUARD summary + per-batch pivot log lines added (`modules/dexbot_cow_runtime.ts`, `modules/dexbot_class.ts`, `modules/order/grid.ts`, `modules/dexbot_maintenance_runtime.ts`, `modules/order/manager.ts`, new `tests/test_stale_guard_pivot_fixes.js`).
+
+### 2026-09-05
+
+- **Feat(cli)**: add `dexbot tv` one-step TradingView chart command — `dexbot tv <bot|pool-id|AssetA/AssetB> [--month N]` pulls 1h candles in chunked 1-month windows and delegates rendering to the TradingView exporter, replacing the manual fetch-then-export two-step; fetcher chunking reused via exported `fetchCandlesSequentially`/`outputPath`/`buildFetchWindowsFromRange`, chain-log mute centralized in `modules/utils/chain_logs.ts`, saved-chart paths print as clickable `file://` links via `toFileUrl` (`scripts/tv.ts`, `dexbot.ts`, `market_adapter/inputs/fetch_lp_data.ts`, `modules/utils/chain_logs.ts`, `analysis/chart_utils.ts`, docs).
+- **Fix(cow)**: clamp COW rotation size to booked remainder for partial surplus — new `clampRotationSizeForPartial` in `modules/order/utils/validate.ts` applied at both rotation-pairing sites (`pairRotations`, `optimizeRebalanceActions`) so rotations sourced from PARTIAL surplus target the booked remainder instead of the hole size, ending the plan→skip→restore loop that stranded holes and left non-contiguous rails (`modules/order/utils/validate.ts`, `modules/order/manager.ts`, `modules/order/utils/system.ts`, `tests/test_cow_master_plan.ts` COW-019).
+- **Fix(credit)**: distinguish Avar/Curr CR lines in `dexbot credit` output — display-only: Avar. CR label orange+bold printed first, Curr. CR label grey+bold with trailing comma, values keep health colors (`scripts/analyze-credit.ts`).
+- **Feat(discovery)**: split HIGH discovery tier into DEXBot2 vs DEXBot1-style by op-77 usage — DEXBot2 broadcasts native `limit_order_update` ops (type 77) for COW re-prices while DEXBot1-style only cancels+recreates, so presence of op 77 in-window assigns flavor; display-only split (score formula unchanged) with Updates column in HIGH tier, summary and `--output-json` carrying flavor/updates (`analysis/bot_usage/kibana_bot_queries.ts`, `analysis/bot_usage/discover_bot_accounts.ts`).
+- **Fix(cli)**: forward `--help`/`-h` to the `credit` and `tv` sub-scripts — the CLI intercepted help flags anywhere in argv and always printed generic help, so `dexbot credit --help` / `dexbot tv --help` never reached the scripts that own their usage text; the dispatcher now resolves the requested command first and lets only scripts with offline help handling (`credit`, `tv`) keep the flag, everything else keeps the generic help (`dexbot.ts`).
+
 ## [1.4.25] - 2026-09-02 - Genesis-Frozen Price-Slot Determinism, Self-Trade & Fill-Guard Hardening, Grid Orphan & Recovery Hardening
 
 ### 2026-08-29

package/README.md

@@ -235,12 +235,13 @@ Defaults in [`modules/constants.ts`](modules/constants.ts) are overridable at gl
 
 ## 🎯 Zero-Dependency Process Management
 
-`dexbot start` is the recommended production runtime (global install). Repo-root users can run `./unlock` instead. It runs the selected bot set as one monolithic bot process, with the credential daemon and market adapter in separate helper processes. Monolithic start/stop/restart controls apply to the whole runtime, not to individual bots.
+`dexbot start` is the recommended production runtime (global install). Repo-root users can run `./unlock` instead. It runs the selected bot set as one monolithic bot process, with the credential daemon and market adapter in separate helper processes. Monolithic start/stop/reload/restart controls apply to the whole runtime, not to individual bots.
 
 ```bash
 dexbot start/stop          # Stop/start the monolithic runtime
 dexbot start --dryrun      # Dry-run (no transactions broadcast)
-dexbot restart             # Restart the monolithic runtime
+dexbot reload              # Reload the runtime (leaves credential daemon untouched)
+dexbot restart             # Restart the runtime (re-unlocks credential daemon)
 dexbot delete              # Shut down and clean up
 ```
 
@@ -260,6 +261,8 @@ dexbot enable {all|<bot>}  # Enable bot in config
 dexbot stat                # Runtime status (unlock or PM2)
 dexbot order [<bot>]       # Analyze order grids
 dexbot order --export      # Export as HTML to analysis/charts/
+dexbot tv <bot|pool|A/B>   # TradingView 1h chart with AMA overlay (default: 3 months)
+dexbot credit [<bot>]      # Live summed MPA + borrowed-credit positions per asset per bot
 
 dexbot update              # Update DEXBot2
 dexbot clear               # Clear log files
@@ -272,6 +275,7 @@ PM2 is optional — `dexbot start` is the native solution.
 
 ```bash
 dexbot pm2 [<bot>]                         # Start with PM2
+dexbot pm2 reload {all|<bot>}              # Reload managed apps, dexbot-cred untouched
 dexbot pm2 restart {all|<bot>|dexbot-cred} # Safe restart
 dexbot pm2 stop {all|<bot>}                # Stop (via wrapper)
 dexbot pm2 delete {all|<bot>}              # Delete (via wrapper)

package/analysis/README.md

@@ -24,7 +24,7 @@ Tools that inspect DEXBot trading behavior and the market data it operates on. O
 | [`grid_correction_check.ts`](#grid-correction-check-grid_correction_checkts) | "Is my grid placing orders monotonically?" — sell/buy price inversion detector | `npm run analysis:grid-check -- --bot-key <bot-key>` |
 | [`analyze_risk_profile.ts`](#risk-profile-analyzer-analyze_risk_profilets) | "How wide should my Safe Range clamps be?" | `node dist/analysis/analyze_risk_profile.js --bot-key <bot-key>` |
 | [`analyze_trade_heatmap.ts`](#trade-heatmap-analyze_trade_heatmapts) | "Where did trade volume cluster vs the AMA?" | `node dist/analysis/analyze_trade_heatmap.js --bot-key <bot-key>` |
-| [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `npm run analysis:tradingview -- --source market_adapter --bot-key <bot-key>` |
+| [`tradingview/analyze_tradingview.ts`](#tradingview-chart-tradingviewanalyze_tradingviewts) | "Just give me a candle chart" | `dexbot tv <bot-key>` |
 | [`analyze_dynamic_weight.ts`](#dynamic-weight-research-analyze_dynamic_weightts) | "Are buy/sell weights tuned for this regime?" | `node dist/analysis/analyze_dynamic_weight.js --bot-key <bot-key>` |
 | [`analyze_volatility.ts`](#volatility-analyze_volatilityts) | "Both weights clipped too hard / not enough?" | `node dist/analysis/analyze_volatility.js --bot-key <bot-key>` |
 | [`analyze_regime.ts`](#supporting-sub-signals) | "Is the trend/chaos gate too aggressive?" | `node dist/analysis/analyze_regime.js --bot-key <bot-key>` |
@@ -138,8 +138,8 @@ Fetches `fill_order` operations for a BitShares account from Kibana within a spe
 # Account by ID, last 7 days (default)
 node dist/analysis/trade_profitability.js 1.2.123456
 
-# Account by name with on-chain resolution
-node dist/analysis/trade_profitability.js "my-account-name" --lookup --hours 720
+# Account by name (auto-resolved in the background)
+node dist/analysis/trade_profitability.js "my-account-name" --hours 720
 
 # Absolute window with asset filter
 node dist/analysis/trade_profitability.js 1.2.123456 \
@@ -162,7 +162,8 @@ node dist/analysis/trade_profitability.js 1.2.123456 \
 | `--end <iso>` | — | End time |
 | `--hours <n>` | `168` (7d) | Lookback hours (alternative to start/end) |
 | `--asset <id>` | all | Filter to one base asset ID |
-| `--lookup` | off | Resolve account name to 1.2.x ID via BitShares node |
+| `--lookup` | off | Legacy (no-op): account names always resolve automatically |
+| `--refresh-account` | off | Force re-resolution and update the stored `accountId` |
 | `--node <url>` | first healthy from built-in pool (10 nodes) | BitShares node for account + asset resolution |
 | `--csv <file>` | — | Export chronologically sorted trade list |
 | `--json <file>` | — | Export full analysis with per-pair PnL data |
@@ -240,7 +241,7 @@ npm run analysis:grid-check -- --bot-key <bot-key> --per-fill --hours 168
 npm run analysis:grid-check -- --bot-key <bot-key> --hours 168 --tolerance 0.1
 ```
 
-Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolve via `profiles/bots.json` (`--list-bots` to enumerate); the account defaults to the bot's `preferredAccount` and can be overridden with `--account <1.2.x|name>`.
+Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolve via `profiles/bots.json` (`--list-bots` to enumerate); the account defaults to the bot's stored `accountId` when present (no chain lookup — the ID is auto-saved next to `preferredAccount` after the first successful name resolution, re-verified with `--refresh-account`), otherwise `preferredAccount` is resolved on-chain, and can be overridden with `--account <1.2.x|name>`.
 
 <details><summary>Options (click to expand)</summary>
 
@@ -250,7 +251,8 @@ Exit code `0` = pass, `2` = violations found, `1` = fatal error. Bot keys resolv
 | `--hours <n>` | `168` | Lookback hours from now |
 | `--start <iso>` / `--end <iso>` | — | Absolute time window |
 | `--account <id>` | bot `preferredAccount` | Override account ID or name |
-| `--lookup` | off | Resolve account name to 1.2.x via BitShares node |
+| `--lookup` | off | Legacy (no-op): account names always resolve via BitShares node when no stored ID exists |
+| `--refresh-account` | off | Force re-resolution of `preferredAccount` and update the stored `accountId` when it changed |
 | `--node <url>` | first built-in node | Node for account/asset resolution |
 | `--per-fill` | off | Check at fill granularity instead of per-order aggregated |
 | `--include-cross-pair` | off | Also check consecutive fills across different pairs |
@@ -309,7 +311,12 @@ node dist/analysis/analyze_trade_heatmap.js \
 Generates a standalone TradingView-style HTML chart with candle OHLC, SMA, AMA, VWMA, and volume panel. See [tradingview/README.md](tradingview/README.md) for full documentation.
 
 ```bash
-# Bot-key (auto-resolves candle file and AMA settings)
+# Recommended one-step: bot, pool, or pair (fetches candles + renders, default 3 months)
+dexbot tv <bot-key>
+dexbot tv 133
+dexbot tv TOKENA/TOKENB
+
+# Manual: bot-key (auto-resolves candle file and AMA settings)
 npm run analysis:tradingview -- --source market_adapter --bot-key <bot-key>
 
 # From an explicit candle file

package/analysis/ama_fitting/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ama_fitting",
-  "version": "1.4.25",
+  "version": "1.5.1",
   "description": "Tools for fitting AMA parameters to market data",
   "main": "../../dist/analysis/ama_fitting/optimizer_high_resolution.js",
   "scripts": {

package/analysis/analyze_derivatives.ts

@@ -14,7 +14,7 @@
  *
  *   node dist/analysis/analyze_derivatives.js \\
  *     --source market_adapter \
- *     --bot-key XRP-BTS
+ *     --bot-key AAA-BBB
  *
  * Output:
  *   analysis/charts/derivative_chart.html

package/analysis/bot_key_utils.ts

@@ -4,7 +4,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PATHS } from '../modules/paths.js';
 import { getStorage } from '../modules/storage/index.js';
-const { readJSON } = getStorage();
+const { readJSON, writeJSON } = getStorage();
+import { parseJsonWithComments } from '../modules/order/utils/system.js';
 import { MARKET_ADAPTER } from '../modules/constants.js';
 import { loadMarketProfiles } from './tradingview/tradingview_uplot_chart_generator.js';
 import { sanitizeKey } from '../modules/utils/sanitize_key.js';
@@ -22,7 +23,13 @@ function loadBotSettings(filePath = PATHS.PROFILES.BOTS_JSON) {
     try {
         return readJSON(filePath);
     } catch (_) {
-        return null;
+        // The bot editor reads/writes through a comment-tolerant parser, so
+        // operator comments may legally exist — fall back before giving up.
+        try {
+            return parseJsonWithComments(fs.readFileSync(filePath, 'utf8'));
+        } catch (_) {
+            return null;
+        }
     }
 }
 
@@ -70,6 +77,268 @@ function loadBotMeta(botKey: any, filePath = PATHS.PROFILES.BOTS_JSON) {
     return loose || null;
 }
 
+/**
+ * Locate the source span of the entryIndex-th object literal inside the
+ * top-level "bots" array of a (possibly comment-bearing) JSON document.
+ * Strings and // + block comments are skipped while scanning, so braces
+ * inside them never disturb the balance count. Returns null when the
+ * document shape is unexpected — callers fall back to a full rewrite.
+ */
+function findBotsEntrySpan(raw: string, entryIndex: number): { start: number; end: number } | null {
+    const m = /"bots"\s*:\s*\[/.exec(raw);
+    if (!m) return null;
+    let i = m.index + m[0].length; // just past '['
+    const n = raw.length;
+    let count = 0;
+    const skipWsComments = () => {
+        while (i < n) {
+            const c = raw[i];
+            if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+            if (c === '/' && raw[i + 1] === '/') { while (i < n && raw[i] !== '\n') i++; continue; }
+            if (c === '/' && raw[i + 1] === '*') { i += 2; while (i < n && !(raw[i] === '*' && raw[i + 1] === '/')) i++; i += 2; continue; }
+            break;
+        }
+    };
+    const skipString = () => {
+        const q = raw[i];
+        i++;
+        while (i < n) {
+            const c = raw[i];
+            if (c === '\\') { i += 2; continue; }
+            if (c === q) { i++; return; }
+            i++;
+        }
+    };
+    // Skip one JSON value starting at raw[i]; false on malformed input.
+    const skipValue = (): boolean => {
+        skipWsComments();
+        if (i >= n) return false;
+        const c = raw[i];
+        if (c === '"' || c === "'") { skipString(); return true; }
+        if (c === '{' || c === '[') {
+            const open = c;
+            const close = c === '{' ? '}' : ']';
+            i++;
+            let depth = 1;
+            while (i < n && depth > 0) {
+                const d = raw[i];
+                if (d === '"' || d === "'") { skipString(); continue; }
+                if (d === '/' && raw[i + 1] === '/') { while (i < n && raw[i] !== '\n') i++; continue; }
+                if (d === '/' && raw[i + 1] === '*') { i += 2; while (i < n && !(raw[i] === '*' && raw[i + 1] === '/')) i++; i += 2; continue; }
+                if (d === open) depth++;
+                else if (d === close) depth--;
+                i++;
+            }
+            return depth === 0;
+        }
+        while (i < n && raw[i] !== ',' && raw[i] !== ']' && raw[i] !== '}') i++;
+        return true;
+    };
+    for (;;) {
+        skipWsComments();
+        if (i >= n) return null;
+        if (raw[i] === ']') return null; // array ended before entryIndex
+        if (raw[i] === '{') {
+            const start = i;
+            if (!skipValue()) return null;
+            if (count === entryIndex) return { start, end: i };
+            count++;
+        } else if (!skipValue()) {
+            return null;
+        }
+        skipWsComments();
+        if (i < n && raw[i] === ',') { i++; continue; }
+        if (i < n && raw[i] === ']') return null;
+        return null; // malformed separator
+    }
+}
+
+/**
+ * Locate the string value of a top-level key inside one bot-entry source
+ * span. Unlike a regex, this scan skips over // and block comments as well
+ * as string literals, so a key-looking fragment inside a comment (e.g.
+ * `// "accountId": "1.2.9999" (old)`) can never be mistaken for the real
+ * key. Returns the span of the quoted value (including quotes), or null
+ * when the key is absent or its value is not a string.
+ */
+function findEntryKeyValueSpan(entrySrc: string, key: string): { valueStart: number; valueEnd: number } | null {
+    const n = entrySrc.length;
+    const isWs = (c: string) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
+    let i = 0;
+    let depth = 0;
+    while (i < n) {
+        const c = entrySrc[i];
+        if (isWs(c)) { i++; continue; }
+        if (c === '/' && entrySrc[i + 1] === '/') { while (i < n && entrySrc[i] !== '\n') i++; continue; }
+        if (c === '/' && entrySrc[i + 1] === '*') { i += 2; while (i < n && !(entrySrc[i] === '*' && entrySrc[i + 1] === '/')) i++; i += 2; continue; }
+        if (c === '{' || c === '[') { depth++; i++; continue; }
+        if (c === '}' || c === ']') { depth--; i++; continue; }
+        if (c !== '"') { i++; continue; }
+        // String literal: read it (honoring backslash escapes).
+        let j = i + 1;
+        let str = '';
+        while (j < n) {
+            const d = entrySrc[j];
+            if (d === '\\') { str += entrySrc.slice(j, j + 2); j += 2; continue; }
+            if (d === '"') break;
+            str += d; j++;
+        }
+        if (j >= n) return null;
+        const closingQuote = j;
+        if (depth !== 1 || str !== key) { i = closingQuote + 1; continue; }
+        // Candidate key at top level: expect `:` then a quoted value.
+        let k = closingQuote + 1;
+        while (k < n && isWs(entrySrc[k])) k++;
+        if (entrySrc[k] !== ':') { i = closingQuote + 1; continue; }
+        k++;
+        while (k < n && isWs(entrySrc[k])) k++;
+        if (entrySrc[k] !== '"') { i = closingQuote + 1; continue; }
+        let m = k + 1;
+        while (m < n) {
+            const e = entrySrc[m];
+            if (e === '\\') { m += 2; continue; }
+            if (e === '"') return { valueStart: k, valueEnd: m + 1 };
+            m++;
+        }
+        return null;
+    }
+    return null;
+}
+
+/**
+ * Byte-preserving accountId update: replaces the value in place, or inserts
+ * `"accountId"` right after `"preferredAccount"` keeping the line indent, so
+ * comments, key order and formatting elsewhere in the file survive. The
+ * patched document is re-parsed (comments allowed) and the value asserted
+ * before the atomic tmp+rename write. Returns false on any uncertainty —
+ * callers fall back to a full rewrite.
+ */
+function patchAccountIdInRaw(filePath: string, entryIndex: number, accountId: string): boolean {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    } catch (_) {
+        return false;
+    }
+    const span = findBotsEntrySpan(raw, entryIndex);
+    if (!span) return false;
+    const entrySrc = raw.slice(span.start, span.end);
+    let patchedEntry: string | null = null;
+    const idSpan = findEntryKeyValueSpan(entrySrc, 'accountId');
+    if (idSpan) {
+        patchedEntry = entrySrc.slice(0, idSpan.valueStart)
+            + `"${accountId}"`
+            + entrySrc.slice(idSpan.valueEnd);
+    } else {
+        const prefSpan = findEntryKeyValueSpan(entrySrc, 'preferredAccount');
+        if (!prefSpan) return false;
+        const lineStart = entrySrc.lastIndexOf('\n', prefSpan.valueEnd) + 1;
+        const indentMatch = /^[ \t]*/.exec(entrySrc.slice(lineStart));
+        const indent = indentMatch ? indentMatch[0] : '  ';
+        patchedEntry = entrySrc.slice(0, prefSpan.valueEnd)
+            + `,\n${indent}"accountId": "${accountId}"`
+            + entrySrc.slice(prefSpan.valueEnd);
+    }
+    if (!patchedEntry || patchedEntry === entrySrc) return false;
+    const patched = raw.slice(0, span.start) + patchedEntry + raw.slice(span.end);
+    try {
+        const reparsed = parseJsonWithComments(patched);
+        const checkEntries = Array.isArray(reparsed?.bots) ? reparsed.bots : [];
+        if (checkEntries[entryIndex]?.accountId !== accountId) return false;
+    } catch (_) {
+        return false;
+    }
+    const tmpPath = `${filePath}.tmp-persist-${process.pid}-${Date.now()}`;
+    try {
+        fs.writeFileSync(tmpPath, patched, 'utf8');
+        fs.renameSync(tmpPath, filePath);
+        return true;
+    } catch (_) {
+        try { fs.unlinkSync(tmpPath); } catch (_) { /* best-effort cleanup */ }
+        return false;
+    }
+}
+
+/**
+ * Persist a resolved account name → ID mapping onto the bot entry in
+ * profiles/bots.json (`accountId` next to `preferredAccount`), so analysis
+ * tools can skip the chain lookup on subsequent runs. No-op when the stored
+ * value already matches. Prefers a byte-preserving textual patch (comments,
+ * key order and formatting survive); falls back to a full rewrite using the
+ * same atomic writeJSON serialization the bot editor uses. Returns true when
+ * the file was updated.
+ */
+function persistBotAccountId(botKey: any, accountId: string, filePath = PATHS.PROFILES.BOTS_JSON): boolean {
+    if (!botKey || !/^1\.2\.\d+$/.test(String(accountId))) return false;
+    let settings: any = null;
+    try {
+        settings = loadBotSettings(filePath);
+    } catch (_) {
+        return false;
+    }
+    const entries = Array.isArray(settings?.bots) ? settings.bots : [];
+    const normalizedKey = String(botKey).toLowerCase();
+    const index = entries.findIndex((bot: any, i: number) => computeBotKey(bot, i) === normalizedKey);
+    if (index < 0 || entries[index]?.accountId === accountId) return false;
+    try {
+        if (patchAccountIdInRaw(filePath, index, String(accountId))) return true;
+    } catch (_) {
+        // Fall through to the full rewrite below.
+    }
+    entries[index].accountId = String(accountId);
+    try {
+        writeJSON(filePath, settings);
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+/**
+ * Return the stored chain account ID for a bot key, or null when none is
+ * stamped yet. When expectedRef is given, the stored ID is only returned if
+ * the entry's current preferredAccount still matches it — a rename must
+ * never silently reuse a stale ID.
+ */
+function getStoredBotAccountId(botKey: any, expectedRef?: string | null, filePath = PATHS.PROFILES.BOTS_JSON): string | null {
+    if (!botKey) return null;
+    let meta: any = null;
+    try {
+        meta = loadBotMeta(botKey, filePath);
+    } catch (_) {
+        return null;
+    }
+    const stored = meta && /^1\.2\.\d+$/.test(String(meta.accountId ?? '')) ? String(meta.accountId) : null;
+    if (!stored) return null;
+    if (expectedRef != null && String(meta.preferredAccount ?? '').toLowerCase() !== String(expectedRef).toLowerCase()) return null;
+    return stored;
+}
+
+/**
+ * Find the bot entry whose preferredAccount matches a raw account reference
+ * (case-insensitive). Used by tools that accept a bare account name to locate
+ * the stored accountId and the persist target. Returns null for 1.2.x input
+ * or when no bot claims the name.
+ */
+function findBotKeyByAccountRef(ref: any, filePath = PATHS.PROFILES.BOTS_JSON): { botKey: string; meta: any } | null {
+    if (!ref || /^1\.2\.\d+$/.test(String(ref))) return null;
+    let settings: any = null;
+    try {
+        settings = loadBotSettings(filePath);
+    } catch (_) {
+        return null;
+    }
+    const entries = Array.isArray(settings?.bots) ? settings.bots : [];
+    const want = String(ref).toLowerCase();
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry && String(entry.preferredAccount ?? '').toLowerCase() === want) {
+            return { botKey: computeBotKey(entry, i), meta: entry };
+        }
+    }
+    return null;
+}
+
 function resolveAmaConfig(botKey: any) {
     const botMeta = loadBotMeta(botKey);
     // Unknown bot key: fall back to the global erSmoothPeriod default (same
@@ -153,5 +422,5 @@ function resolveAmaKey(botKey: any) {
     return 'AMA3';
 }
 
-export { loadBotSettings, sanitizeKey, computeBotKey, resolveBotKey, candleFileForBot, resolveCandleFile, loadBotMeta, resolveAmaConfig, resolveAmaKey }
+export { loadBotSettings, sanitizeKey, computeBotKey, resolveBotKey, candleFileForBot, resolveCandleFile, loadBotMeta, getStoredBotAccountId, findBotKeyByAccountRef, persistBotAccountId, resolveAmaConfig, resolveAmaKey }