dexbot 1.7.1 → 1.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/analysis/grid_correction_check.d.ts +60 -1
  6. package/dist/analysis/grid_correction_check.js +268 -18
  7. package/dist/analysis/pivot_timeline.d.ts +78 -0
  8. package/dist/analysis/pivot_timeline.js +360 -0
  9. package/dist/market_adapter/utils/file_lock.js +16 -4
  10. package/dist/modules/account_bots.d.ts +7 -0
  11. package/dist/modules/account_bots.js +7 -5
  12. package/dist/modules/bot_defaults.js +6 -1
  13. package/dist/modules/constants.d.ts +14 -0
  14. package/dist/modules/constants.js +82 -2
  15. package/dist/modules/dexbot_class.d.ts +39 -0
  16. package/dist/modules/dexbot_class.js +86 -1
  17. package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
  18. package/dist/modules/dexbot_cow_runtime.js +299 -75
  19. package/dist/modules/dexbot_maintenance_runtime.d.ts +32 -2
  20. package/dist/modules/dexbot_maintenance_runtime.js +196 -16
  21. package/dist/modules/dexbot_state_recovery.js +15 -1
  22. package/dist/modules/launcher/instance_lock.d.ts +27 -0
  23. package/dist/modules/launcher/instance_lock.js +131 -0
  24. package/dist/modules/node_flap_score.d.ts +6 -6
  25. package/dist/modules/node_flap_score.js +6 -6
  26. package/dist/modules/order/accounting.d.ts +9 -4
  27. package/dist/modules/order/accounting.js +89 -26
  28. package/dist/modules/order/async_lock.d.ts +7 -1
  29. package/dist/modules/order/async_lock.js +7 -1
  30. package/dist/modules/order/export.js +25 -18
  31. package/dist/modules/order/fill_ledger.d.ts +99 -0
  32. package/dist/modules/order/fill_ledger.js +103 -0
  33. package/dist/modules/order/grid.d.ts +94 -18
  34. package/dist/modules/order/grid.js +247 -75
  35. package/dist/modules/order/grid_reconcile_internal.js +16 -4
  36. package/dist/modules/order/index.d.ts +29 -6
  37. package/dist/modules/order/index.js +5 -5
  38. package/dist/modules/order/lifecycle.js +3 -3
  39. package/dist/modules/order/manager.d.ts +36 -24
  40. package/dist/modules/order/manager.js +159 -39
  41. package/dist/modules/order/placement_lock.d.ts +30 -0
  42. package/dist/modules/order/placement_lock.js +48 -0
  43. package/dist/modules/order/sync_engine.d.ts +66 -118
  44. package/dist/modules/order/sync_engine.js +118 -162
  45. package/dist/modules/order/utils/math.d.ts +7 -3
  46. package/dist/modules/order/utils/math.js +7 -3
  47. package/dist/modules/order/utils/order.d.ts +79 -42
  48. package/dist/modules/order/utils/order.js +183 -86
  49. package/dist/modules/order/utils/system.d.ts +192 -8
  50. package/dist/modules/order/utils/system.js +534 -34
  51. package/dist/modules/paths.d.ts +1 -0
  52. package/dist/modules/paths.js +1 -0
  53. package/dist/modules/timing_policy.js +4 -2
  54. package/dist/modules/types.d.ts +49 -27
  55. package/dist/pm2.js +126 -0
  56. package/dist/unlock.js +26 -1
  57. package/docs/COW_INVARIANTS.md +5 -1
  58. package/docs/DEXBOT_COMPARISON.md +5 -5
  59. package/docs/EVOLUTION.md +10 -8
  60. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  61. package/docs/GRID_RECONCILE.md +3 -3
  62. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +192 -31
  63. package/docs/README.md +1 -1
  64. package/docs/architecture.md +26 -8
  65. package/modules/README.md +4 -0
  66. package/package.json +4 -3
@@ -112,6 +112,7 @@ declare const PATHS: {
112
112
  ECOSYSTEM_CONFIG_JS: string;
113
113
  SUPERVISOR_SOCK: string;
114
114
  MONOLITHIC_PID: string;
115
+ INSTANCE_LOCKS_DIR: string;
115
116
  MONOLITHIC_BOT_PID: string;
116
117
  MONOLITHIC_BOT_INFO: string;
117
118
  MONOLITHIC_CRED_PID: string;
@@ -308,6 +308,7 @@ const PATHS = {
308
308
  ECOSYSTEM_CONFIG_JS: path.join(PROFILES_DIR, 'ecosystem.config.cjs'),
309
309
  SUPERVISOR_SOCK: path.join(PROFILES_DIR, 'supervisor.sock'),
310
310
  MONOLITHIC_PID: path.join(PROFILES_DIR, 'monolithic.pid'),
311
+ INSTANCE_LOCKS_DIR: path.join(PROFILES_DIR, 'instance-locks'),
311
312
  MONOLITHIC_BOT_PID: path.join(PROFILES_DIR, 'monolithic-bot.pid'),
312
313
  MONOLITHIC_BOT_INFO: path.join(PROFILES_DIR, 'monolithic-bot.json'),
313
314
  MONOLITHIC_CRED_PID: path.join(PROFILES_DIR, 'monolithic-cred.pid'),
@@ -107,8 +107,10 @@ export const TIMING_CLASSIFICATIONS = Object.freeze({
107
107
  SPREAD_STALE_ESCALATE_MS: { kind: 'policy', rationale: 'Out-of-spread persistence before escalation.' },
108
108
  SPREAD_STALE_FUND_ESCALATE_MS: { kind: 'policy', rationale: 'Shortened escalation window when the cause is fundability.' },
109
109
  SPREAD_STALE_GEOMETRY_ESCALATE_MS: { kind: 'policy', rationale: 'Shortened escalation window when the cause is geometry.' },
110
+ SPREAD_STALE_PIVOT_EXPIRE_MS: { kind: 'policy', rationale: 'Pivot lifetime after the one re-center per fill before the guard references are expired outright.' },
110
111
  SPREAD_STALE_IN_TOLERANCE_RESET_MS: { kind: 'policy', rationale: 'How long in-tolerance must hold before the watchdog resets.' },
111
112
  SPREAD_STALE_RESYNC_COOLDOWN_MS: { kind: 'policy', rationale: 'Rate limit on spread-correction resyncs.' },
113
+ SPREAD_STALE_RECHECK_MS: { kind: 'policy', rationale: 'Level-triggered recheck cadence while the spread is out of tolerance (the documented watchdog clocks assume evaluation).' },
112
114
  SPREAD_STALE_TRANSIENT_GRACE: { kind: 'policy', rationale: 'Consecutive transient corrections tolerated before escalating.' },
113
115
  SPREAD_STALE_WARN_MS: { kind: 'policy', rationale: 'Out-of-spread persistence before a warning.' },
114
116
  TARGETED_DRIFT_SYNC_COOLDOWN_MS: { kind: 'policy', rationale: 'Rate limit on targeted drift syncs.' },
@@ -169,8 +171,8 @@ export const TIMING_CLASSIFICATIONS = Object.freeze({
169
171
  },
170
172
  FILL_DEDUPE_WINDOW_MS: {
171
173
  kind: 'self-healing',
172
- rationale: 'Coalescing window for duplicate fill events.',
173
- removal: 'Delete when fill identity is a chain tuple (tx+op) everywhere; the window would then be redundant with that key.',
174
+ rationale: 'Lease on a fill CLAIM accepted but not yet booked (deferral/crash). The processed-fill store refuses a booked key while retained, at any age; FILL_RECORD_RETENTION_MS bounds retention, not an expiry.',
175
+ removal: 'Delete once startup recovery reconciles a restored claim against chain-balance evidence (recomputing the credit from chain truth) instead of bounding it by age.',
174
176
  },
175
177
  });
176
178
  /**
@@ -146,24 +146,17 @@ export interface ChainOrdersLike {
146
146
  wasRecentlyOwnCancelled?(orderId: string): boolean;
147
147
  [key: string]: unknown;
148
148
  }
149
- /**
150
- * Minimal runtime surface shared by the `dexbot_*_runtime.ts` layer. This is
151
- * a seeded interface to grow as each runtime file is typed — the index
152
- * signature keeps the many `_camelCase` internals reachable (as `unknown`)
153
- * while the common surface gets real types. Replace index-signature reads with
154
- * named fields as the relevant owners are typed.
155
- */
156
- /**
157
- * The DexBot runtime surface used by the `dexbot_*_runtime.ts` layer (and the
158
- * `DexBot` class itself, which structurally satisfies it). No index signature:
159
- * every member the runtime touches is enumerated, so a typo or an undeclared
160
- * internal is a compile error instead of a silent `unknown`.
161
- */
162
149
  /** Credential-daemon signing token (used until the private key is unlocked). */
163
150
  export interface SigningToken {
164
151
  accountName: string;
165
152
  socketPath?: string;
166
153
  }
154
+ /**
155
+ * The `DEXBot` runtime surface used by the `dexbot_*_runtime.ts` layer (the
156
+ * `DEXBot` class itself structurally satisfies it). No index signature: every
157
+ * member the runtime touches is enumerated, so a typo or an undeclared internal
158
+ * is a compile error instead of a silent `unknown`.
159
+ */
167
160
  export interface BotLike {
168
161
  config: GridConfig;
169
162
  manager: OrderManagerLike;
@@ -246,6 +239,15 @@ export interface BotLike {
246
239
  * persistence clock — it must hold for SPREAD_STALE_IN_TOLERANCE_RESET_MS.
247
240
  */
248
241
  _outOfSpreadToleranceSince: number;
242
+ /**
243
+ * One-shot level-triggered spread recheck while the grid is out of
244
+ * tolerance (the base maintenance cadence can be hours; every watchdog
245
+ * clock assumes the check is evaluated).
246
+ */
247
+ _spreadRecheckTimer: ReturnType<typeof setTimeout> | null;
248
+ _spreadRecheckInFlight: boolean;
249
+ /** A placement that did not reduce the violation was already reported. */
250
+ _outOfSpreadNoProgressWarned: boolean;
249
251
  _strandedHoldSince: Map<string, number>;
250
252
  _recoverySyncInFlight: number;
251
253
  _batchInFlight: number;
@@ -543,6 +545,16 @@ export interface BotMetrics extends UnknownRecord {
543
545
  spreadCorrectionRefusalCauses: Record<string, number>;
544
546
  /** Bounded re-plan retries attempted after a transient spread-correction refusal. */
545
547
  spreadCorrectionRetryCount: number;
548
+ /** Stale plans dropped because there was no fill context to re-plan from (batch not broadcast). */
549
+ stalePlanDroppedCount: number;
550
+ /** Stale fill batches that proceeded anyway at the re-plan limit (bounded policy). */
551
+ stalePlanProceedCount: number;
552
+ /** Size updates skipped because a PARTIAL slot's booked remaining already matched (post-fill growth refused). */
553
+ clampedNoopUpdateCount: number;
554
+ /** Planned operations thrown away when a definitive chunk failure aborted the remaining chunks. */
555
+ chunkAbortedOpCount: number;
556
+ /** Rails re-placed by the post-recovery rebalance (snapshot reload / repair contexts). */
557
+ reloadReplacedRailCount: number;
546
558
  }
547
559
  /** An unmatched chain order surfaced by a sync pass. */
548
560
  export interface UnmatchedChainOrder extends UnknownRecord {
@@ -742,11 +754,11 @@ interface AccountTotalsGate {
742
754
  ok: boolean;
743
755
  [key: string]: unknown;
744
756
  }
745
- /** Accountant surface the sync engine calls directly. */
746
757
  /** Result of `accountant.processFillAccounting()`. */
747
758
  interface FillAccountingResult extends UnknownRecord {
748
759
  status: string;
749
760
  }
761
+ /** Accountant surface the sync engine calls directly. */
750
762
  interface AccountantLike {
751
763
  processFillAccounting(fillOp: unknown, fillKey: string, options?: UnknownRecord): Promise<boolean>;
752
764
  adjustTotalBalance(orderType: string, delta: number, operation: string): Promise<unknown>;
@@ -914,6 +926,8 @@ export interface AccountOrdersLike {
914
926
  }
915
927
  /** Batch-persistence handle for processed fill keys. */
916
928
  export interface ProcessedFillStoreLike {
929
+ /** In-memory booked keys (key -> processedAt). The dedupe authority at credit time. */
930
+ tracker: Map<string, number>;
917
931
  configure(options?: {
918
932
  accountOrders?: AccountOrdersLike | null;
919
933
  }): void;
@@ -958,17 +972,6 @@ interface ManagerRecoveryState {
958
972
  structuralResyncRequested?: boolean;
959
973
  [key: string]: unknown;
960
974
  }
961
- /**
962
- * The contract the order engine consumes from `OrderManager`. This is the
963
- * decoupled interface the `modules/order/**` layer types its `manager`
964
- * parameters against, so the engine does not need to import the concrete
965
- * class (avoiding a runtime import cycle). `OrderManager` structurally
966
- * satisfies it.
967
- *
968
- * Optional members are either wired in later by the runtime layer
969
- * (e.g. `requestStructuralGridResync`, `notifyBoundaryUpdate`) or read only
970
- * defensively; keep them optional so partial test doubles still type-check.
971
- */
972
975
  /**
973
976
  * Three-valued result of an operation whose outcome is not always knowable.
974
977
  *
@@ -1036,6 +1039,17 @@ export interface CreditRuntimeLike {
1036
1039
  runCreditWatchdog(): Promise<unknown>;
1037
1040
  shutdown(): Promise<unknown>;
1038
1041
  }
1042
+ /**
1043
+ * The contract the order engine consumes from `OrderManager`. This is the
1044
+ * decoupled interface the `modules/order/**` layer types its `manager`
1045
+ * parameters against, so the engine does not need to import the concrete
1046
+ * class (avoiding a runtime import cycle). `OrderManager` structurally
1047
+ * satisfies it.
1048
+ *
1049
+ * Optional members are either wired in later by the runtime layer
1050
+ * (e.g. `requestStructuralGridResync`, `notifyBoundaryUpdate`) or read only
1051
+ * defensively; keep them optional so partial test doubles still type-check.
1052
+ */
1039
1053
  export interface OrderManagerLike {
1040
1054
  /**
1041
1055
  * Unified order-lifecycle read surface (see modules/order/lifecycle.ts).
@@ -1136,6 +1150,7 @@ export interface OrderManagerLike {
1136
1150
  _pauseRecalcLogging: boolean;
1137
1151
  _throwOnIllegalState: boolean;
1138
1152
  _fillBatchInFlight: number;
1153
+ _gridUpdateBlockedCycles?: number;
1139
1154
  _fillProcessingLock: ManagerLock;
1140
1155
  _syncLock: ManagerLock;
1141
1156
  _divergenceLock: ManagerLock;
@@ -1191,6 +1206,14 @@ export interface OrderManagerLike {
1191
1206
  _lastMarketFillPrice?: number | null;
1192
1207
  _lastMarketFillType?: string | null;
1193
1208
  _lastMarketFillAt?: number | null;
1209
+ /**
1210
+ * Refused (off-market) fill level: a fill the pivot-arming policy refused
1211
+ * (§9.12/P1) still marks its own level as a same-level re-fill block for a
1212
+ * short TTL (§9.12/P2 amended). In-memory only — never persisted.
1213
+ */
1214
+ _lastRefusedFillPrice?: number | null;
1215
+ _lastRefusedFillType?: string | null;
1216
+ _lastRefusedFillAt?: number | null;
1194
1217
  _liveMarketPrice?: number | null;
1195
1218
  _liveMarketPriceAt?: number | null;
1196
1219
  _liveMarketPriceAttemptedAt?: number | null;
@@ -1267,14 +1290,13 @@ export interface OrderManagerLike {
1267
1290
  _clearStalePlacementRegion?: (maxAgeMs?: number, options?: {
1268
1291
  batchInFlightMs?: number;
1269
1292
  }) => boolean;
1270
- /** Pass-1 chain-size markers (see note/consumeChainSizeAppliedFill). */
1293
+ /** Pass-1 chain-size markers (see note/consumeChainSizeAppliedFillAmount). */
1271
1294
  _chainSizeAppliedFills?: Map<string, {
1272
1295
  filledInt: number;
1273
1296
  at: number;
1274
1297
  }>;
1275
1298
  noteChainSizeAppliedFill?: (orderId: string, filledInt: number, maxAgeMs?: number) => void;
1276
1299
  consumeChainSizeAppliedFillAmount?: (orderId: string, filledInt: number, maxAgeMs?: number) => number;
1277
- consumeChainSizeAppliedFill?: (orderId: string, filledInt: number, maxAgeMs?: number) => boolean;
1278
1300
  snapshotChainSizeAppliedFills?: () => Record<string, {
1279
1301
  filledInt: number;
1280
1302
  at: number;
package/dist/pm2.js CHANGED
@@ -83,6 +83,7 @@ import { existsSync } from 'node:fs';
83
83
  import { parseJsonWithComments } from './modules/order/utils/system.js';
84
84
  import { readBotsFileWithLock } from './modules/bots_file_lock.js';
85
85
  import { loadSettingsFile, selectActiveBotEntries } from './modules/bot_settings.js';
86
+ import { getProcessDiscovery } from './modules/process_discovery.js';
86
87
  import * as chainKeys from './modules/chain_keys.js';
87
88
  import * as credentialPolicy from './modules/credential_policy.js';
88
89
  import { readHeadlessPassword } from './modules/launcher/headless_password.js';
@@ -436,6 +437,20 @@ async function main({ botNameFilter = null, clawOnly = false, headless = false,
436
437
  // prefixed lines process-wide to keep the launcher banner and the
437
438
  // connection confirmation as the only startup output.
438
439
  muteChainLogs();
440
+ // DOUBLE-CONTROLLER GUARD: a monolithic instance started via
441
+ // `dexbot start` is a live controller for the same accounts this PM2
442
+ // fleet is about to own. Two controllers on one account corrupt each
443
+ // other's grids and fills (observed live 2026-11-14), so refuse here
444
+ // instead of letting the per-bot instance lock kill each PM2 app 3
445
+ // seconds later.
446
+ const monoPid = readLiveMonolithicPidLite();
447
+ if (monoPid > 0) {
448
+ console.error(pm2Error(`DEXBot2 is already running outside PM2 (monolithic PID ${monoPid}).\n` +
449
+ `Starting the PM2 fleet now would put two controllers on the same accounts.\n` +
450
+ `Stop it first with 'dexbot stop', then rerun this command.`));
451
+ await flushVersionStatusOrHeader(versionStatus);
452
+ process.exit(1);
453
+ }
439
454
  await waitForConnected(TIMING.CONNECTION_TIMEOUT_MS);
440
455
  console.log(pm2Success('Connected to BitShares'));
441
456
  }
@@ -471,6 +486,7 @@ async function main({ botNameFilter = null, clawOnly = false, headless = false,
471
486
  console.log();
472
487
  // Step 4: Start PM2
473
488
  console.log(clawOnly ? 'Starting PM2 with credential daemon only...' : 'Starting PM2 with all services...');
489
+ await warnStaleDexbotApps(apps);
474
490
  await startManagedAppsPM2(apps);
475
491
  console.log();
476
492
  console.log('='.repeat(50));
@@ -522,6 +538,116 @@ function startManagedAppsPM2(apps) {
522
538
  }
523
539
  return startPM2Process(['start', ECOSYSTEM_FILE]);
524
540
  }
541
+ /**
542
+ * Lightweight "a `dexbot start` monolithic instance is live" probe.
543
+ *
544
+ * Reads the monolithic pid file, so it must confirm the pid still belongs to
545
+ * an unlock process (a recycled pid must not block PM2 forever). Kept local
546
+ * instead of importing launcher/monolithic_runtime: pm2.ts is loaded by the
547
+ * ESM-mocked launcher tests, and that module drags in the whole launcher graph
548
+ * (bot settings, supervisor, credential runtime) for one check. The
549
+ * authoritative backstop remains the per-bot instance lock.
550
+ *
551
+ * @returns {number} Live monolithic pid, or 0 when absent/dead/unrelated
552
+ */
553
+ function readLiveMonolithicPidLite() {
554
+ try {
555
+ const pid = Number(storage.readFile(PATHS.PROFILES.MONOLITHIC_PID).trim());
556
+ if (!Number.isInteger(pid) || pid <= 0)
557
+ return 0;
558
+ const discovery = getProcessDiscovery();
559
+ if (!discovery.isAlive(pid))
560
+ return 0;
561
+ const cmdline = discovery.readCmdline(pid);
562
+ if (!/(^|[\\/])unlock\.(?:js|ts)(?:\0|$| )/.test(cmdline))
563
+ return 0;
564
+ return pid;
565
+ }
566
+ catch (_) {
567
+ return 0;
568
+ }
569
+ }
570
+ /**
571
+ * Names of PM2 apps that are RUNNING dexbot bot/runtime scripts from this
572
+ * project root. Returns [] when pm2 is unavailable or the query fails — the
573
+ * caller treats that as "cannot know", never as "none running".
574
+ */
575
+ async function listRunningDexbotAppNames() {
576
+ try {
577
+ const list = await runPm2Raw(['jlist'], { timeoutMs: 15000 });
578
+ if (list.code !== 0)
579
+ return [];
580
+ const parsed = JSON.parse(list.stdout || '[]');
581
+ if (!Array.isArray(parsed))
582
+ return [];
583
+ const names = [];
584
+ for (const app of parsed) {
585
+ const env = app?.pm2_env;
586
+ if (!env)
587
+ continue;
588
+ if (String(env.pm_cwd || '') !== PATHS.PROJECT_ROOT)
589
+ continue;
590
+ if (!/(^|[\\/])(bot|dexbot|market_adapter|credential-daemon)\.(?:js|ts)$/.test(String(env.pm_exec_path || '')))
591
+ continue;
592
+ const status = String(env.status || '');
593
+ if (status && status !== 'online' && status !== 'launching')
594
+ continue;
595
+ if (typeof app.name === 'string' && app.name)
596
+ names.push(app.name);
597
+ }
598
+ return names;
599
+ }
600
+ catch (_) {
601
+ return [];
602
+ }
603
+ }
604
+ /**
605
+ * Warn about RUNNING dexbot apps from this project root whose names are not in
606
+ * the current bots.json set (renamed bots, leftovers from an older ecosystem
607
+ * generation, a hung interactive-unlock attempt). Such an app comes back on
608
+ * every `pm2 resurrect`/reboot and can double-run an account against the
609
+ * freshly generated fleet — the exact double-controller incident of
610
+ * 2026-11-14. Warn only (never auto-delete): the single-controller instance
611
+ * lock refuses them at runtime, and deleting operator processes silently
612
+ * would hide the misconfiguration instead of surfacing it.
613
+ *
614
+ * Compared against the FULL configured bot set (not the possibly bot-filtered
615
+ * `apps` subset) so `dexbot pm2 <bot>` does not flag the operator's other,
616
+ * legitimately configured bots.
617
+ */
618
+ async function warnStaleDexbotApps(apps) {
619
+ try {
620
+ const running = await listRunningDexbotAppNames();
621
+ if (running.length === 0)
622
+ return;
623
+ const current = new Set((apps || []).map((a) => a.name));
624
+ // Full configured set from bots.json (not the possibly bot-filtered
625
+ // `apps` subset). Best-effort: a settings read failure just narrows
626
+ // the comparison to `apps` instead of blocking startup.
627
+ const configured = new Set();
628
+ try {
629
+ if (storage.exists(BOTS_JSON)) {
630
+ const { config } = loadSettingsFile(BOTS_JSON);
631
+ for (const b of selectActiveBotEntries(config)) {
632
+ if (b && b.active !== false && b.name)
633
+ configured.add(String(b.name));
634
+ }
635
+ }
636
+ }
637
+ catch (_) { /* best-effort */ }
638
+ const serviceNames = new Set(['dexbot-adapter', 'dexbot-update', 'dexbot-cred']);
639
+ for (const name of running) {
640
+ if (current.has(name) || configured.has(name) || serviceNames.has(name))
641
+ continue;
642
+ if ([...current].some((n) => isSameBotName(n, name)) || [...configured].some((n) => isSameBotName(n, name)))
643
+ continue;
644
+ console.warn(`[PM2] Stale dexbot app '${name}' is RUNNING but not in the current bots.json set ` +
645
+ `(renamed bot or leftover from an older config). It will keep running across reboots and ` +
646
+ `can double-run an account. Remove it with: pm2 delete ${name} && pm2 save`);
647
+ }
648
+ }
649
+ catch (_) { /* diagnostics only — must never block startup */ }
650
+ }
525
651
  function startCredentialDaemonPM2({ credentialEnv = {} } = {}) {
526
652
  const app = buildCredentialDaemonApp({ credentialEnv });
527
653
  const args = [
package/dist/unlock.js CHANGED
@@ -75,7 +75,7 @@ const { ensureDir } = storage;
75
75
  const { createBotSupervisor, SOCKET_PATH, forwardSignal, isPidAlive, waitForPidExit, readMarketAdapterLockPid, stopMarketAdapterFromLock, usesAmaGridPrice, waitForChildSpawn, pidMatchesScriptCandidates, candidateRuntimeScriptPaths, } = require('./modules/launcher/bot_supervisor');
76
76
  const { statusTitle, statusLabel, statusBool, statusActiveBotName, statusSuccess, statusError, colorStatus, STATUS_COLORS, readProcStat, readProcMemMB, readProcCpuTime, readProcCpuPercent, readProcUptime, formatMemoryWithUptime, printControlStatus, } = require('./modules/launcher/status_reporting');
77
77
  const { MONOLITHIC_PID_FILE, MONOLITHIC_BOT_PID_FILE, MONOLITHIC_BOT_INFO_FILE, MONOLITHIC_CRED_PID_FILE, MONOLITHIC_OUT_LOG, MONOLITHIC_ERROR_LOG, CREDENTIAL_SOCKET_FILE, cleanupStateFiles, readLiveMonolithicPid, readMonolithicBotInfo, isLikelyCredentialDaemonProcess, isExpectedMonolithicBotPid, isProcessInDstate, stopCredentialDaemonPid, stopCredentialDaemon, ensureNoForeignCredentialDaemon, findCredentialSocketOwnerPid, cleanupCredentialRuntimeFiles, readCredentialDaemonStatus, ensureLogDir: ensureMonolithicLogDir, buildDexbotStartArgs, createUpdateScheduler, listConfiguredBots, getControlBotNames, getControlActionLabel, getControlServiceNames, resolveControlRouting, botNotFoundMessage, printControlActionSummary, formatBotCount, } = require('./modules/launcher/monolithic_runtime');
78
- const { isConfiguredBotName } = require('./modules/launcher/runtime_mode');
78
+ const { isConfiguredBotName, listDexbotPm2Processes } = require('./modules/launcher/runtime_mode');
79
79
  const CODE_ROOT = __dirname;
80
80
  const BOTS_FILE = PATHS.PROFILES.BOTS_JSON;
81
81
  const LOGS_DIR = PATHS.LOGS_DIR;
@@ -519,6 +519,31 @@ async function main({ argv = process.argv, startupGraceMs = DEFAULT_STARTUP_GRAC
519
519
  return;
520
520
  }
521
521
  }
522
+ // DOUBLE-CONTROLLER GUARD: refuse to start bots that a PM2 fleet is
523
+ // already running (same names). Two controllers on one account corrupt
524
+ // each other's grids and fills (observed live 2026-11-14); fail here with
525
+ // the offending app names instead of letting the per-bot instance lock
526
+ // kill the freshly unlocked bots one by one. Internal children skip the
527
+ // check — their parent launcher already ran it.
528
+ if (!clawOnly && !dryrun && !isInternalChild && launchedBotNames.length > 0) {
529
+ // listDexbotPm2Processes() already gates on the pm2 daemon pid file
530
+ // (no subprocess when PM2 was never run) and keeps only DEXBot2's own
531
+ // processes, so this stays a cheap, offline-safe probe.
532
+ const runningApps = listDexbotPm2Processes()
533
+ .map((p) => String(p?.name || ''))
534
+ .filter(Boolean);
535
+ const overlap = runningApps.filter((appName) => launchedBotNames.some((b) => isSameBotName(b, appName)));
536
+ if (overlap.length > 0) {
537
+ printLauncherHeader({ botName: effectiveBotName || botName, clawOnly, creditOnly, isolated, dryrun, headless });
538
+ console.error(`The following bot(s) are already running under PM2: ${overlap.join(', ')}.\n` +
539
+ `Starting them here too would put two controllers on the same accounts.\n` +
540
+ `Stop the PM2 fleet first: dexbot pm2 stop ${overlap.join(' ')}\n` +
541
+ ` (or run the bots under PM2 instead: dexbot pm2)`);
542
+ await flushVersionStatusOrHeader(versionStatus);
543
+ process.exitCode = 1;
544
+ return;
545
+ }
546
+ }
522
547
  try {
523
548
  if (!isDetachedSupervisorChild) {
524
549
  printLauncherHeader({ botName: effectiveBotName || botName, clawOnly, creditOnly, isolated, dryrun, headless });
@@ -221,6 +221,8 @@ not by the seven per-site structures that used to disagree
221
221
  - `INV-SYNC-008` SPREAD-typed fills resolve the real side
222
222
  - A SPREAD slot can carry an on-chain order (spread-correction activation). Fill processing must resolve the real BUY/SELL side (chain order type, pays asset, or price-vs-startPrice convention) before pushing the fill or computing the transition.
223
223
  - A SPREAD-typed fill would silently drop the `deriveTargetBoundary` shift and produce an illegal SPREAD+on-chain state rejected by `validateOrder`.
224
+ - The pays-asset mapping has ONE implementation (`order/fill_ledger.ts` `resolveTradedSide`, used by `_computeFillContext`, the unmatched-fill attribution and the queued pivot refresh). The SPREAD price fallback stays with the caller that owns the ladder (`resolveSpreadOrderSide`).
225
+ - `slot.type` is the ACCOUNTING side and is retagged to the traded side by a partial-fill transition (so `size` stays dimensionally consistent for `recalculateFunds`). It is NOT rail identity: a repair proof must also read the level's geometry (`geometryTypeForSlotIndex`), and a fill-retagged slot on the opposite rail is still wrong-side. See `docs/FILL_PIPELINE.md` INV-FILL-002/INV-FILL-006.
224
226
 
225
227
  ---
226
228
 
@@ -307,7 +309,9 @@ not by the seven per-site structures that used to disagree
307
309
  - SELL placements must use nearest available free slots first (ascending price).
308
310
 
309
311
  - `INV-RECON-006` Fresh-placement cancels are deferred for a grace window
310
- - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written by the lifecycle write funnel (and by `recordOrderPlacement` for manager-shaped callers) into `manager._placedAt`, and tested by `isFreshlyPlacedOrder`.
312
+ - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written only by the lifecycle write funnel into `manager._placedAt`, and tested by `isFreshlyPlacedOrder`.
313
+ - **Exemption (chain-observed wrong side).** A CANCEL for an order the correction queue holds as a chain-observed `typeMismatch` (`entry.typeMismatch === true` with a `chainOrderId`) is exempt: the chain already proved the side is wrong, so parking it adds a second 15-minute wait after the pre-batch drain deferred (active region) or failed. A plan-shaped CANCEL whose reason is `type-mismatch` is NOT exempt — it only proves master ≠ target, which is the stale-target lag this grace exists for. The exemption is a queue-provenance fact, not a grid blocker: see `docs/FILL_PIPELINE.md` INV-FILL-004.
314
+ - A queued `typeMismatch` entry stays valid while the level's stored type OR its rail geometry still disagrees with the chain side; a retagged `slot.type` alone is not a repair (INV-SYNC-008 / `docs/FILL_PIPELINE.md` INV-FILL-006).
311
315
  - `COWRebalanceEngine.execute` drops the whole slot's action group for a deferred cancel (dropping only the CANCEL would let a paired CREATE fold back into an UPDATE and re-materialize the placement), then re-syncs the deferred slots from master via `workingGrid.syncFromMaster` so the commit does not virtualize a still-live order.
312
316
  - Divergence correction (`applyGridDivergenceCorrections`) applies the same guard after dropping any queued committed-size UPDATE for the not-desired/size-0 slot.
313
317
  - `grid-load`/`grid-init` load contexts are excluded so restarts do not suppress the sweep.
@@ -1,7 +1,7 @@
1
1
  # DEXBot vs DEXBot2 — Detailed Comparison Report
2
2
 
3
3
  > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
4
- > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.1).
4
+ > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.3).
5
5
  > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@
36
36
 
37
37
  | Attribute | DEXBot (original) | DEXBot2 |
38
38
  |---|---|---|
39
- | **Release Track** | 1.0.0 | v1.7.1 |
39
+ | **Release Track** | 1.0.0 | v1.7.3 |
40
40
  | **Language** | Python 3.6+ | TypeScript 5.x |
41
41
  | **Status** | Released 1.0.0, unmaintained | Active development |
42
42
  | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -776,10 +776,10 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.7.1 |
779
+ | **Release Track** | 1.0.0 | v1.7.3 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
- | **Last Commit** | May 23, 2020 | 2026-11-04 |
782
- | **Total Commits** | 2281 | 2,492 (current HEAD, v1.7.1 line) |
781
+ | **Last Commit** | May 23, 2020 | 2026-11-17 |
782
+ | **Total Commits** | 2281 | 2,517 (current HEAD, v1.7.3 line) |
783
783
  | **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
784
784
  | **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
785
785
  | **Test Files** | 16 Python test files | 367 `test_*.ts` files (350 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.1 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.3 stable release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,492 commits over ~9 active months
9
+ - **Growth Phase**: 2,517 commits over ~11 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
- - **Stability**: Progression from manual testing to a suite of 353 automated test files (14 live tests skipped)
12
- - **Releases**: 152 version entries in the changelog (v0.1.0 to v1.7.1)
11
+ - **Stability**: Progression from manual testing to a suite of 366 automated test files (live tests included in `test:live`)
12
+ - **Releases**: 154 changelog entries (v0.1.0 to v1.7.3)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
149
149
 
150
150
  ## Version History
151
151
 
152
- Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-04). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,385 (`v0.1.0..HEAD`) and 2,492 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
152
+ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-11-17). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,410 (`v0.1.0..HEAD`) and 2,517 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
153
153
 
154
154
  | Era | Commits | Theme |
155
155
  |-----|--------:|-------|
@@ -178,11 +178,13 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
178
178
  | v1.6.17 → v1.6.18 | 19 | Partial-fill re-anchor recovery (stale-evac skip, residual allow-list, crawl subsumption, rotation-only repair), rail-derived boundary + live fill/chain prices, edge-fill pivot exclusion, guard arity pinning with explicit re-arm, per-slot last-fill exclusion count, CLI `--flag=value` walker, `__test` seam guard, export-surface cleanup |
179
179
  | v1.6.18 → v1.7.0 | 11 | Liquidity depth chart + `dexbot liquid`/`liq`/`liqu`, `dexbot asset` supply distribution shortcut, pool id/pool-token chart targets + shared spawn runner, case-insensitive asset lookup, asset-report chain-request cuts, shared CLI terminal output, orphan-fill attribution + dark-level revive, stale-grid re-buy discipline, pivot clock provenance & read-time TTL |
180
180
  | v1.7.0 → v1.7.1 | 22 | One existence record per slot (life-cycle registry, unknown-is-never-gone), typed three-valued broadcast outcome, timing-window policy inventory, reconciliation interleaving fuzzer, one writer per life-cycle clock, serialized placement region with lease re-verification, fill-marker idempotency, forced-retreat gap evacuation + committed-geometry sweep, unknown-gap-geometry fix, replay-safe stranded-boundary repair, stability-ranked node selection + flap scoring, chain-account `<bot>` targets for `credit`/`order`, fee-adjusted pool depth chart with both spreads, atomic branch promotion preflight |
181
+ | v1.7.1 → v1.7.2 | 14 | One fill contract + fill-pipeline ratchet, fail-closed grid-update blockers with bounded escalation, single fill identity (`fill_ledger`), credit-time fill-key claim with all-or-nothing balance credits, single-winner concurrent claim, removal of the duplicate applied-amount channel and the second grace-stamp writer, COW broadcast-region leak repair, chain-observed wrong-side cancel exemptions, fill side derived from the paid asset + rail-geometry repair check, fill-anchored rebuild/load boundary, spread rotation into orphaned rail slots, consecutive grid-blocked escalation counter, live-suite env fix |
182
+ | v1.7.2 → v1.7.3 | 10 | Plan-region serialization (`plan → broadcast → commit`), per-account single-controller lock & cross-runtime start guards, market-bounded last-fill pivot + stale pivot expiry, refused-fill same-level refill guard & policy-aware audit mirror, in-place missing UPDATE target repair, settled-pipeline structural resync gate, snapshot reload absence-grace preservation, clamped PARTIAL-growth update skip |
181
183
 
182
184
  ---
183
185
 
184
186
  **Report Originally Generated**: February 19, 2026
185
- **Last Updated**: November 4, 2026
186
- **Total Commits**: 2,492
187
- **Date Range**: December 2, 2025 – November 4, 2026
187
+ **Last Updated**: November 17, 2026
188
+ **Total Commits**: 2,517
189
+ **Date Range**: December 2, 2025 – November 17, 2026
188
190
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -805,4 +805,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
805
805
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
806
806
 
807
807
  ---
808
- *Technical Reference for DEXBot2 v1.7.1 release*
808
+ *Technical Reference for DEXBot2 v1.7.3 release*
@@ -131,9 +131,9 @@ remain unchanged.
131
131
 
132
132
  **Fresh-placement grace (`TIMING.SURPLUS_CANCEL_GRACE_MS`, 15 min):** surplus
133
133
  and cancel-only cancellations also skip any order whose `orderId` was placed
134
- inside the grace window. The timestamp is written by the lifecycle write funnel
135
- (and by `recordOrderPlacement` for manager-shaped callers) into
136
- `manager._placedAt` and tested with `isFreshlyPlacedOrder`; the reconciler's CANCEL
134
+ inside the grace window. The timestamp is written only by the lifecycle write
135
+ funnel (`_syncLifecycleFromMutation` -> `markPlaced`) into `manager._placedAt`
136
+ and tested with `isFreshlyPlacedOrder`; the reconciler's CANCEL
137
137
  actions are filtered by `COWRebalanceEngine.execute`, which drops the whole slot's
138
138
  action group (a paired CANCEL+CREATE must not lose only its CANCEL, or the CREATE
139
139
  folds back into an UPDATE and re-materializes the placement) and re-syncs the