dexbot 1.6.8 → 1.6.9

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 (37) hide show
  1. package/CHANGELOG.md +24 -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/dexbot.js +44 -21
  6. package/dist/market_adapter/core/market_adapter_service.d.ts +81 -1
  7. package/dist/market_adapter/core/market_adapter_service.js +225 -18
  8. package/dist/market_adapter/core/signals/hurst_analyzer.d.ts +10 -1
  9. package/dist/market_adapter/core/signals/hurst_analyzer.js +40 -18
  10. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.d.ts +26 -2
  11. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.js +132 -29
  12. package/dist/market_adapter/core/strategies/regime_gate.d.ts +61 -3
  13. package/dist/market_adapter/core/strategies/regime_gate.js +207 -7
  14. package/dist/market_adapter/interval_utils.d.ts +18 -1
  15. package/dist/market_adapter/interval_utils.js +31 -1
  16. package/dist/market_adapter/market_adapter.d.ts +151 -2
  17. package/dist/market_adapter/market_adapter.js +378 -62
  18. package/dist/market_adapter/test_helpers.d.ts +2 -2
  19. package/dist/market_adapter/test_helpers.js +2 -2
  20. package/dist/market_adapter/utils/file_json_cache.d.ts +29 -0
  21. package/dist/market_adapter/utils/file_json_cache.js +106 -0
  22. package/dist/modules/config.d.ts +6 -0
  23. package/dist/modules/config.js +1 -0
  24. package/dist/modules/constants.d.ts +5 -1
  25. package/dist/modules/constants.js +41 -14
  26. package/dist/modules/order/grid.js +95 -25
  27. package/dist/modules/version_notice.d.ts +166 -20
  28. package/dist/modules/version_notice.js +401 -56
  29. package/dist/pm2.js +9 -2
  30. package/dist/unlock.js +7 -7
  31. package/docs/DEXBOT_COMPARISON.md +3 -3
  32. package/docs/EVOLUTION.md +13 -12
  33. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  34. package/docs/GRID_RECALCULATION.md +6 -2
  35. package/docs/README.md +2 -2
  36. package/market_adapter/README.md +28 -0
  37. package/package.json +1 -1
@@ -21,23 +21,40 @@
21
21
  * prompt).
22
22
  * 2. NEVER THROWS. Every failure path — offline, DNS failure, slow registry,
23
23
  * unreadable cache, browser — resolves to `null`.
24
- * 3. NO SUBPROCESSES. The registry is queried with a single HTTPS GET and a
24
+ * 3. NO SUBPROCESSES. Each source is queried with a single HTTPS GET and a
25
25
  * hard timeout. `execSync('npm view ...')` (as used by `dexbot update`)
26
26
  * costs 1-3s of spawn and hard-depends on the npm CLI, neither of which is
27
27
  * acceptable on the launcher critical path.
28
+ * 3b. MULTIPLE SOURCES, FALLBACK NOT FAILURE. One source is a single point of
29
+ * failure: a host that cannot reach registry.npmjs.org (firewall, DNS, a
30
+ * proxy only the npm CLI knows about) reported "unknown" forever even when
31
+ * the release was published on GitHub. Sources are tried in order and the
32
+ * first answer wins, so an unreachable registry degrades to a slower probe
33
+ * instead of a permanent "?". Each source is bounded by an even share of
34
+ * the total budget, so a hanging first source cannot starve the second.
35
+ * 3c. NEVER MYSTERY. Every failure path records WHY (`ENOTFOUND`, `HTTP 403`,
36
+ * `timeout`, `no fetch`, …) and the unknown verdict names it. An operator
37
+ * cannot act on "?" and used to have to guess between DNS, TLS, a proxy and
38
+ * a timeout.
28
39
  * 4. THROTTLED + NOTIFY-ONCE. A check runs at most once per
29
- * `UPDATER.NOTICE_INTERVAL_MS`, and the same version is announced only once
30
- * (`notifiedVersion` in the cache) so an ignored notice does not nag on
31
- * every restart. A new published version resets that latch. The latch is
32
- * committed by `printVersionStatus` only AFTER the notice is displayed, so a
40
+ * `UPDATER.NOTICE_INTERVAL_MS` AFTER A SUCCESS, and once per
41
+ * `UPDATER.NOTICE_RETRY_MS` after a failure (a failure is the observation
42
+ * that decays fastest — see the constant). The same version is announced
43
+ * only once (`notifiedVersion` in the cache) so an ignored notice does not
44
+ * nag on every restart. A new published version resets that latch. The latch
45
+ * is committed by `printVersionStatus` only AFTER the notice is displayed, so a
33
46
  * launcher path that returns without printing cannot silently consume it —
34
47
  * it is re-offered once the throttle window expires. A throttled run still
35
48
  * reports a status (from the cached observation) so `dexbot stat` answers
36
49
  * "am I current?" without spending a request.
50
+ * 4a. DEFERRED, NOT DROPPED. Callers that have other work to do (`dexbot stat`
51
+ * prints a process table) start the probe, do their work, and flush the
52
+ * verdict when it lands. Nothing is printed speculatively and nothing is
53
+ * ever truncated by an early `process.exit()`.
37
54
  * 4b. ONE IMPLEMENTATION. Every consumer (`unlock`, `pm2`, `dexbot stat`) goes
38
- * through `startVersionStatusCheck` → `printVersionStatus`; the colour of the
39
- * status line, the hint wording and the latch all live here, so no caller can
40
- * drift from another.
55
+ * through this module — `startVersionStatusCheck` / `startStagedVersionStatus`
56
+ * → `printVersionStatus`; the colour of the status line, the hint wording
57
+ * and the latch all live here, so no caller can drift from another.
41
58
  * 5. SILENT WHEN DISABLED. `Config.DEXBOT_SKIP_VERSION_NOTICE=1` (tests, CI,
42
59
  * automation) or `UPDATER.NOTICE_ENABLED: false` short-circuits before any
43
60
  * network or filesystem work.
@@ -71,7 +88,12 @@ const MAX_TIMEOUT_MS = 10_000;
71
88
  * producing NaN ordering.
72
89
  */
73
90
  export function compareVersions(a, b) {
74
- const parse = (v) => String(v ?? '').trim().split(/[-+]/)[0].split('.').map((n) => parseInt(n, 10) || 0);
91
+ // The leading `v` is stripped because the two sources spell it
92
+ // differently: a GitHub release tag is `v1.6.8`, the npm dist-tag document
93
+ // says `1.6.8`. Without this, `v1.6.8` parsed to [0,6,8] and compared as
94
+ // an ancient version — a source-spelling artefact masquerading as "an
95
+ // update is available".
96
+ const parse = (v) => String(v ?? '').trim().replace(/^[vV]/, '').split(/[-+]/)[0].split('.').map((n) => parseInt(n, 10) || 0);
75
97
  const na = parse(a);
76
98
  const nb = parse(b);
77
99
  const len = Math.max(na.length, nb.length);
@@ -96,14 +118,92 @@ export function detectInstallKind(projectRoot = PATHS.PROJECT_ROOT) {
96
118
  }
97
119
  return 'other';
98
120
  }
121
+ /** npm's dist-tag document: `{ "version": "1.6.8", ... }`. */
122
+ const NPM_EXTRACT = (body) => typeof body?.version === 'string' && body.version.trim() ? body.version.trim() : null;
123
+ /**
124
+ * GitHub's latest-release document: `{ "tag_name": "v1.6.8", ... }`. The tag
125
+ * is normalised (leading `v` dropped) by `compareVersions`, so the two
126
+ * sources are directly comparable.
127
+ */
128
+ const GITHUB_EXTRACT = (body) => {
129
+ const tag = body?.tag_name ?? body?.name;
130
+ return typeof tag === 'string' && tag.trim() ? tag.trim() : null;
131
+ };
132
+ /**
133
+ * Derive the GitHub "latest release" endpoint from the configured repository
134
+ * URL, so a fork or a self-hosted mirror is honoured without a second hardcoded
135
+ * owner/repo. Returns null for anything that is not a github.com repository —
136
+ * a non-GitHub host has a different API shape and guessing it would produce a
137
+ * guaranteed-wrong request on every probe.
138
+ */
139
+ export function deriveGithubReleaseUrl(repositoryUrl, apiBase) {
140
+ const raw = String(repositoryUrl ?? '').trim();
141
+ if (!raw)
142
+ return null;
143
+ const m = raw.match(/^https?:\/\/(?:[^@/]+@)?github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?\/?$/i);
144
+ if (!m)
145
+ return null;
146
+ const base = String(apiBase || 'https://api.github.com').replace(/\/+$/, '');
147
+ return `${base}/repos/${m[1]}/${m[2]}/releases/latest`;
148
+ }
149
+ /**
150
+ * The probe's sources, in priority order.
151
+ *
152
+ * npm FIRST, GitHub second — measured, and the order is load-bearing:
153
+ *
154
+ * latency a wash. Warm, interleaved: npm p50 21ms / github p50 18ms.
155
+ * Cold process: npm 92-102ms / github 97-99ms. GitHub being
156
+ * ~3ms "faster" is noise, not a reason to reorder.
157
+ * payload npm 8KB vs github 40KB (the release document carries the
158
+ * body, assets and author objects). 5x for the same answer.
159
+ * rate limit the GitHub API is 60 requests/hour per IP unauthenticated
160
+ * and answers 403 when spent; npm has no comparable ceiling.
161
+ * Our own 12h throttle keeps us far below it, but a shared
162
+ * server IP or a retry burst is not ours to control.
163
+ * AUTHORITY the deciding one. The release pipeline creates the GitHub
164
+ * release FIRST and publishes to npm ~4-9 minutes LATER
165
+ * (1.6.8 10:15:14Z vs 10:24:00Z; 1.6.7 09:08:48 vs 09:13:15;
166
+ * 1.6.6 00:49:52 vs 00:54:27). GitHub-first would therefore
167
+ * spend that window telling operators a new version exists
168
+ * while `dexbot update` still installs the old one — a hint
169
+ * that is not merely early but wrong. npm lagging by the same
170
+ * minutes is harmless: it says "up to date" a little longer.
171
+ *
172
+ * The cost of this order is the one case that measurably suffers: on a host
173
+ * that cannot reach the registry at all, the fallback answer arrives after the
174
+ * first source's share of the budget is spent (~1.6s of the 3s), versus ~20ms
175
+ * if GitHub went first. That is the right trade — a slow answer is still an
176
+ * answer, and the alternative is an answer that is wrong for the first minutes
177
+ * of every release.
178
+ */
179
+ export function resolveReleaseSources(options = {}) {
180
+ const sources = [];
181
+ const npmUrl = options.registryUrl !== undefined ? options.registryUrl : UPDATER?.REGISTRY_URL;
182
+ if (npmUrl)
183
+ sources.push({ id: 'npm', url: String(npmUrl), extract: NPM_EXTRACT });
184
+ const configured = options.githubReleaseUrl !== undefined
185
+ ? options.githubReleaseUrl
186
+ : UPDATER?.GITHUB_RELEASE_URL;
187
+ // 'off' (any case) disables the fallback explicitly; an empty value means
188
+ // "derive it from the repository we already know about".
189
+ const disabled = typeof configured === 'string' && ['off', 'none', 'false', 'disabled'].includes(configured.trim().toLowerCase());
190
+ const githubUrl = disabled
191
+ ? null
192
+ : (String(configured ?? '').trim() || deriveGithubReleaseUrl(options.repositoryUrl !== undefined ? options.repositoryUrl : UPDATER?.REPOSITORY_URL, options.apiBase ?? UPDATER?.GITHUB_API_BASE ?? 'https://api.github.com'));
193
+ if (githubUrl)
194
+ sources.push({ id: 'github', url: githubUrl, extract: GITHUB_EXTRACT });
195
+ return sources;
196
+ }
99
197
  /**
100
198
  * The single status line, shared by `dexbot stat` and every launcher start.
101
199
  *
102
- * GREEN when the install matches the registry, ORANGE when a newer release
103
- * exists, GRAY when the probe could not answer (offline / throttled with no
104
- * prior observation) — an unknown answer must never be rendered as "up to
105
- * date". The installed version is always named, so a caller never needs a
106
- * second "DEXBot2 vX.Y.Z" header of its own.
200
+ * GREEN when the install matches the published version, ORANGE when a newer
201
+ * release exists, GRAY when the probe could not answer (offline / throttled
202
+ * with no prior observation) — an unknown answer must never be rendered as
203
+ * "up to date". The installed version is always named, so a caller never needs
204
+ * a second "DEXBot2 vX.Y.Z" header of its own. The unknown verdict carries the
205
+ * probe's reason, because an unnamed "?" tells the operator nothing they can
206
+ * act on.
107
207
  */
108
208
  export function formatVersionStatusLine(status) {
109
209
  const c = CLI_COLORS;
@@ -114,7 +214,13 @@ export function formatVersionStatusLine(status) {
114
214
  if (status.state === 'update-available') {
115
215
  return `${current} ${c.orange}⬆${c.reset} ${c.orange}A new version is available: v${status.latestVersion}.${c.reset}`;
116
216
  }
117
- return `${current} ${c.gray}? Could not check for a newer version.${c.reset}`;
217
+ // The staged wait gave up: say the information is missing. Distinct from
218
+ // the branch below, where a probe ran and told us it failed.
219
+ if (status.exhausted) {
220
+ return `${current} ${c.gray}? No current version information (${status.reason ?? 'no answer'}).${c.reset}`;
221
+ }
222
+ const why = status.reason ? ` (${status.reason})` : '';
223
+ return `${current} ${c.gray}? Could not check for a newer version${why}.${c.reset}`;
118
224
  }
119
225
  /**
120
226
  * Hint text. `dexbot update` is the correct verb for BOTH layouts: the npm
@@ -161,15 +267,33 @@ function resolveTimeoutMs(override) {
161
267
  return 2_000;
162
268
  return Math.min(raw, MAX_TIMEOUT_MS);
163
269
  }
270
+ /** Turn a thrown fetch error into something an operator can act on. The
271
+ * `cause.code` is the useful part (`ENOTFOUND`, `ECONNREFUSED`,
272
+ * `CERT_HAS_EXPIRED`, `UND_ERR_SOCKET`); the wrapper message is noise. */
273
+ function describeFetchError(err, source, timeoutMs) {
274
+ const code = err?.cause?.code || err?.code;
275
+ if (code)
276
+ return `${source.id}: ${code}`;
277
+ const name = String(err?.name ?? '');
278
+ if (name === 'AbortError' || name === 'TimeoutError')
279
+ return `${source.id}: timeout after ${timeoutMs}ms`;
280
+ const message = String(err?.message ?? '').trim();
281
+ return message ? `${source.id}: ${message.split('\n')[0].slice(0, 60)}` : `${source.id}: request failed`;
282
+ }
164
283
  /**
165
- * Fetch the published `latest` version. Returns null on ANY failure — an
166
- * offline node, a proxy, a 404, a malformed body. Never throws.
284
+ * Query ONE source. Resolves with a version or with a reason; never throws and
285
+ * never rejects, so the sequential fallback in `probeReleaseSources` cannot be
286
+ * short-circuited by a single bad source.
167
287
  */
168
- async function fetchLatestVersion(registryUrl, timeoutMs, fetchImpl) {
288
+ async function fetchFromSource(source, timeoutMs, fetchImpl) {
169
289
  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
170
- if (!doFetch)
171
- return null;
290
+ if (!doFetch) {
291
+ // Node < 18 (or a stripped runtime) has no global fetch. That is a
292
+ // permanent, not transient, condition — say so instead of "unknown".
293
+ return { sourceId: source.id, version: null, reason: `${source.id}: no fetch available (Node >= 18 required)` };
294
+ }
172
295
  const controller = typeof AbortController === 'function' ? new AbortController() : null;
296
+ let timedOut = false;
173
297
  // The attempt never rejects, so racing it cannot leak an unhandled
174
298
  // rejection. The enclosing timeout is a HARD backstop: it resolves even
175
299
  // when no AbortController exists or a custom fetch ignores the signal, so
@@ -178,51 +302,103 @@ async function fetchLatestVersion(registryUrl, timeoutMs, fetchImpl) {
178
302
  // ahead of `process.exit()` and freeze `dexbot start`.
179
303
  const attempt = (async () => {
180
304
  try {
181
- const res = await doFetch(registryUrl, {
305
+ const res = await doFetch(source.url, {
182
306
  method: 'GET',
183
307
  headers: { accept: 'application/json' },
184
308
  signal: controller?.signal,
185
309
  });
186
- if (!res || res.ok === false)
187
- return null;
310
+ if (!res)
311
+ return { sourceId: source.id, version: null, reason: `${source.id}: empty response` };
312
+ if (res.ok === false)
313
+ return { sourceId: source.id, version: null, reason: `${source.id}: HTTP ${res.status}` };
188
314
  const body = await res.json();
189
- const version = body?.version;
190
- if (typeof version !== 'string' || !version.trim())
191
- return null;
192
- return version.trim();
315
+ const version = source.extract(body);
316
+ if (!version)
317
+ return { sourceId: source.id, version: null, reason: `${source.id}: no version in response` };
318
+ return { sourceId: source.id, version };
193
319
  }
194
- catch {
195
- return null;
320
+ catch (err) {
321
+ return { sourceId: source.id, version: null, reason: describeFetchError(err, source, timeoutMs) };
196
322
  }
197
323
  })();
198
324
  let timer = null;
199
325
  const timeout = new Promise((resolve) => {
200
326
  timer = setTimeout(() => {
327
+ timedOut = true;
201
328
  try {
202
329
  controller?.abort();
203
330
  }
204
331
  catch { /* best-effort cancel */ }
205
- resolve(null);
332
+ resolve({ sourceId: source.id, version: null, reason: `${source.id}: timeout after ${timeoutMs}ms` });
206
333
  }, timeoutMs);
207
334
  });
208
335
  try {
209
- return await Promise.race([attempt, timeout]);
336
+ const result = await Promise.race([attempt, timeout]);
337
+ // Prefer the explicit timeout verdict: an aborted fetch usually rejects
338
+ // with a bare "aborted", which is a much worse thing to show.
339
+ return timedOut ? { sourceId: source.id, version: null, reason: `${source.id}: timeout after ${timeoutMs}ms` } : result;
210
340
  }
211
341
  finally {
212
342
  if (timer)
213
343
  clearTimeout(timer);
214
344
  }
215
345
  }
346
+ /**
347
+ * Try the sources in order and take the first answer. The total budget is split
348
+ * EVENLY rather than spent first-come: a source that hangs until the deadline
349
+ * would otherwise leave the fallback with no time at all, which is precisely
350
+ * the case the fallback exists for.
351
+ */
352
+ export async function probeReleaseSources(sources, timeoutMs, fetchImpl) {
353
+ if (!sources.length)
354
+ return { version: null, reasons: ['no version source configured'] };
355
+ const perSource = Math.max(1, Math.floor(timeoutMs / sources.length));
356
+ const reasons = [];
357
+ for (const source of sources) {
358
+ const result = await fetchFromSource(source, perSource, fetchImpl);
359
+ if (result.version)
360
+ return { version: result.version, source: result.sourceId, reasons };
361
+ if (result.reason)
362
+ reasons.push(result.reason);
363
+ }
364
+ return { version: null, reasons };
365
+ }
216
366
  /** Assemble a status; `includeNotice` is false on the throttled path, which
217
367
  * reports the cached observation but never re-announces. */
218
- function buildVersionStatus(currentVersion, latestVersion, installKind, cacheFile, includeNotice) {
368
+ function buildVersionStatus(currentVersion, latestVersion, installKind, cacheFile, includeNotice, extra = {}) {
219
369
  const state = !latestVersion
220
370
  ? 'unknown'
221
371
  : compareVersions(currentVersion, latestVersion) < 0 ? 'update-available' : 'up-to-date';
222
372
  const notice = state === 'update-available' && includeNotice && latestVersion
223
373
  ? { currentVersion, latestVersion, installKind, cacheFile }
224
374
  : null;
225
- return { currentVersion, latestVersion, installKind, state, cacheFile, notice };
375
+ return { currentVersion, latestVersion, installKind, state, cacheFile, notice, ...extra };
376
+ }
377
+ /**
378
+ * How long a cached observation stays valid. A SUCCESS is worth a full
379
+ * `UPDATER.NOTICE_INTERVAL_MS` (12h): the published version does not move under
380
+ * us, and every run consults this cache before spending a request. A FAILURE is
381
+ * re-tried after `UPDATER.NOTICE_RETRY_MS` — throttling a failure for the full
382
+ * success window is what turned one 5s network hiccup into a permanent
383
+ * "could not check", with no retry left to disprove it.
384
+ */
385
+ function resolveThrottleMs(previous, options) {
386
+ // `NOTICE_INTERVAL_MS: 0` is the documented "check on every start" opt-in.
387
+ // It must disable BOTH windows: leaving the failure backoff in force would
388
+ // silently throttle exactly the case an operator turned throttling off to
389
+ // diagnose.
390
+ if (options.intervalMs === 0 || options.retryMs === 0)
391
+ return 0;
392
+ if (Number(UPDATER?.NOTICE_INTERVAL_MS ?? 0) === 0)
393
+ return 0;
394
+ const failed = !previous || previous.latestVersion == null;
395
+ const override = failed ? options.retryMs : options.intervalMs;
396
+ if (override !== undefined)
397
+ return Math.max(0, Number(override) || 0);
398
+ const configured = failed
399
+ ? Number(UPDATER?.NOTICE_RETRY_MS ?? 0)
400
+ : Number(UPDATER?.NOTICE_INTERVAL_MS ?? 0);
401
+ return Number.isFinite(configured) ? configured : 0;
226
402
  }
227
403
  /**
228
404
  * Start the check. Resolves with the installed-vs-published status, plus a
@@ -242,43 +418,55 @@ export function startVersionStatusCheck(options = {}) {
242
418
  return done(null);
243
419
  const cacheFile = options.cacheFile || PATHS.PROFILES.VERSION_CHECK_JSON;
244
420
  const now = options.now ?? Date.now();
245
- const intervalMs = options.intervalMs ?? Number(UPDATER?.NOTICE_INTERVAL_MS ?? 0);
246
421
  const previous = readCache(cacheFile);
247
422
  // `??` (not `||`) so an explicitly empty current version is reported as
248
423
  // "unknown" and stays silent rather than falling back to a real version.
249
424
  const currentVersion = options.currentVersion ?? Config.VERSION;
250
425
  if (!currentVersion)
251
426
  return done(null);
252
- // `!== undefined` (not `||`) so an explicit empty string models a
253
- // deliberately unconfigured registry instead of falling back to UPDATER.
254
- const registryUrl = options.registryUrl !== undefined ? options.registryUrl : UPDATER?.REGISTRY_URL;
255
- if (!registryUrl) {
256
- // No registry configured — do not even write a cache entry, so
427
+ const sources = resolveReleaseSources({
428
+ ...(options.registryUrl !== undefined ? { registryUrl: options.registryUrl } : {}),
429
+ ...(options.githubReleaseUrl !== undefined ? { githubReleaseUrl: options.githubReleaseUrl } : {}),
430
+ });
431
+ if (!sources.length) {
432
+ // No source configured — do not even write a cache entry, so
257
433
  // enabling it later takes effect on the very next start.
258
434
  return done(null);
259
435
  }
260
436
  const installKind = options.installKind || detectInstallKind();
261
- // Throttle: a recent probe (successful OR failed) means stay quiet, so an
262
- // offline node never pays the timeout on every single restart. The cached
263
- // observation still answers "am I current?" without spending a request.
264
- if (!options.force && Number.isFinite(intervalMs) && intervalMs > 0 && previous) {
265
- if (now - previous.lastCheckMs < intervalMs) {
266
- return done(buildVersionStatus(currentVersion, previous.latestVersion, installKind, cacheFile, false));
437
+ // Throttle: a recent probe means stay quiet, so a node never pays the
438
+ // network timeout on every single restart. The cached observation still
439
+ // answers "am I current?" without spending a request — including when the
440
+ // cached observation is a failure, which is rendered WITH its reason.
441
+ const force = options.force ?? Config.DEXBOT_VERSION_CHECK_FORCE;
442
+ const throttleMs = resolveThrottleMs(previous, options);
443
+ if (!force && throttleMs > 0 && previous) {
444
+ if (now - previous.lastCheckMs < throttleMs) {
445
+ return done(buildVersionStatus(currentVersion, previous.latestVersion, installKind, cacheFile, false, {
446
+ source: previous.source,
447
+ reason: previous.latestVersion == null ? previous.lastError : undefined,
448
+ }));
267
449
  }
268
450
  }
269
451
  return (async () => {
270
- const latestVersion = await fetchLatestVersion(registryUrl, resolveTimeoutMs(options.timeoutMs), options.fetchImpl);
452
+ const probe = await probeReleaseSources(sources, resolveTimeoutMs(options.timeoutMs), options.fetchImpl);
453
+ const reason = probe.version ? undefined : (probe.reasons.join('; ') || 'probe failed');
271
454
  // Record the observation but DO NOT latch here: `notifiedVersion` is
272
455
  // advanced by `printVersionStatus` only once the hint is displayed.
273
456
  const base = {
274
457
  version: CACHE_VERSION,
275
458
  updatedAt: new Date(now).toISOString(),
276
459
  lastCheckMs: now,
277
- latestVersion: latestVersion ?? null,
460
+ latestVersion: probe.version ?? null,
278
461
  notifiedVersion: previous?.notifiedVersion ?? null,
462
+ source: probe.source ?? previous?.source,
463
+ lastError: reason,
279
464
  };
280
465
  writeCache(cacheFile, base);
281
- const status = buildVersionStatus(currentVersion, latestVersion, installKind, cacheFile, true);
466
+ const status = buildVersionStatus(currentVersion, probe.version, installKind, cacheFile, true, {
467
+ source: probe.source,
468
+ reason,
469
+ });
282
470
  // Same version already announced: keep reporting the state, drop only
283
471
  // the one-time hint.
284
472
  if (status.notice && previous?.notifiedVersion === status.notice.latestVersion) {
@@ -306,6 +494,10 @@ function latchVersionNotice(notice) {
306
494
  lastCheckMs: existing?.lastCheckMs ?? 0,
307
495
  latestVersion: existing?.latestVersion ?? notice.latestVersion,
308
496
  notifiedVersion: notice.latestVersion,
497
+ // Diagnostics survive the latch, so a later throttled run can still
498
+ // name the source that answered / why the last probe failed.
499
+ source: existing?.source,
500
+ lastError: existing?.lastError,
309
501
  };
310
502
  writeCache(notice.cacheFile, next);
311
503
  }
@@ -335,14 +527,28 @@ export function printVersionStatus(status, options = {}) {
335
527
  console.log();
336
528
  }
337
529
  /**
338
- * Run the check and print the status/notice to stdout. Convenience wrapper
339
- * for call sites with nothing to overlap (e.g. `dexbot status`). Returns the
340
- * status that was printed, or null when the feature is switched off.
530
+ * The entry-point renderer: the status line when there is one, the bare
531
+ * installed-version header when the check is switched off.
532
+ *
533
+ * `printVersionStatus(null)` is a deliberate no-op, which is right for a
534
+ * caller that only wants the line — but every CLI entry point must still name
535
+ * the running build when the notice is disabled
536
+ * (`DEXBOT_SKIP_VERSION_NOTICE=1` / `UPDATER.NOTICE_ENABLED=false`), and
537
+ * re-implementing that fallback per entry point is how they drift: `dexbot
538
+ * stat` had it, `dexbot pm2` did not, so a node with the notice off learned its
539
+ * version from one command and not the other. One helper, one behaviour.
341
540
  */
342
- export async function maybePrintVersionStatus(options = {}) {
343
- const status = await startVersionStatusCheck(options);
344
- printVersionStatus(status, { indent: options.indent, surround: options.surround });
345
- return status;
541
+ export function printVersionStatusOrHeader(status, options = {}) {
542
+ if (status) {
543
+ printVersionStatus(status, options);
544
+ return;
545
+ }
546
+ const indent = options.indent ?? ' ';
547
+ if (options.surround !== false)
548
+ console.log();
549
+ console.log(`${indent}DEXBot2 v${Config.VERSION}`);
550
+ if (options.surround !== false)
551
+ console.log();
346
552
  }
347
553
  /**
348
554
  * Await an already-started check and print its status. The single flush path
@@ -353,12 +559,151 @@ export async function maybePrintVersionStatus(options = {}) {
353
559
  export async function flushVersionStatus(pending) {
354
560
  printVersionStatus(await pending);
355
561
  }
562
+ /**
563
+ * The flush counterpart of `printVersionStatusOrHeader`, for callers that start
564
+ * the probe early and surface it at a terminal point (`unlock.ts`, `pm2.ts`).
565
+ * A null status is the "check switched off" signal, so the installed version is
566
+ * still named - the same single behaviour the stat path gets.
567
+ */
568
+ export async function flushVersionStatusOrHeader(pending) {
569
+ printVersionStatusOrHeader(await pending);
570
+ }
356
571
  /**
357
572
  * Print the status when the probe settles, WITHOUT awaiting it. For launch
358
573
  * paths that must never delay the bot start — the resident process outlives the
359
574
  * probe, so there is no `process.exit()` to truncate it.
575
+ *
576
+ * Uses the header-aware renderer: an entry point must name the running build
577
+ * even when the check is switched off, and this is the non-awaited form of the
578
+ * same contract as `flushVersionStatusOrHeader`.
360
579
  */
361
580
  export function printVersionStatusWhenReady(pending) {
362
- void pending.then(printVersionStatus, () => { });
581
+ void pending.then(printVersionStatusOrHeader, () => { });
582
+ }
583
+ /**
584
+ * Race `promise` against `ms`. Resolves `{ hit: true, value }` when the
585
+ * promise wins and `{ hit: false }` when the timer does. The timer is always
586
+ * cleared once the promise wins, so a fast answer never leaves a pending timer
587
+ * behind — and nothing is unref'd, because a test awaiting `settled` must not
588
+ * have the process exit from under it.
589
+ */
590
+ function settleWithin(promise, ms) {
591
+ if (!Number.isFinite(ms) || ms <= 0) {
592
+ return promise.then((value) => ({ hit: true, value }), () => ({ hit: false }));
593
+ }
594
+ return new Promise((resolve) => {
595
+ let done = false;
596
+ const timer = setTimeout(() => {
597
+ if (done)
598
+ return;
599
+ done = true;
600
+ resolve({ hit: false });
601
+ }, ms);
602
+ promise.then((value) => {
603
+ if (done)
604
+ return;
605
+ done = true;
606
+ clearTimeout(timer);
607
+ resolve({ hit: true, value });
608
+ }, () => {
609
+ if (done)
610
+ return;
611
+ done = true;
612
+ clearTimeout(timer);
613
+ resolve({ hit: false });
614
+ });
615
+ });
616
+ }
617
+ function resolveGraceMs(override) {
618
+ const raw = override !== undefined ? Number(override) : Number(UPDATER?.NOTICE_STAGE_GRACE_MS);
619
+ if (!Number.isFinite(raw) || raw <= 0)
620
+ return 1_000;
621
+ return Math.min(raw, MAX_TIMEOUT_MS);
622
+ }
623
+ /** Budget for the final re-probe; falls back to the launcher default so a
624
+ * malformed settings file cannot turn it into an open-ended hang. */
625
+ function resolveFinalTimeoutMs(override, inherited) {
626
+ const raw = override !== undefined
627
+ ? Number(override)
628
+ : inherited !== undefined
629
+ ? Number(inherited)
630
+ : Number(UPDATER?.NOTICE_STATUS_TIMEOUT_MS ?? UPDATER?.NOTICE_TIMEOUT_MS);
631
+ if (!Number.isFinite(raw) || raw <= 0)
632
+ return 3_000;
633
+ return Math.min(raw, MAX_TIMEOUT_MS);
634
+ }
635
+ /** The explicit "we have no version information" verdict. Distinct from a
636
+ * probe that RAN and failed: here nothing answered at all, and the operator
637
+ * is told the information is missing rather than that the check failed. */
638
+ function buildExhaustedStatus(currentVersion, installKind, cacheFile, sourceLabels, budgetMs) {
639
+ const who = sourceLabels.length ? sourceLabels.join(' / ') : 'the release sources';
640
+ return buildVersionStatus(currentVersion, null, installKind, cacheFile, false, {
641
+ exhausted: true,
642
+ reason: `${who} did not answer within ${budgetMs}ms`,
643
+ });
644
+ }
645
+ /**
646
+ * The one wording a staged caller shows for "we still do not know".
647
+ *
648
+ * Without this, `dexbot stat` could end on either "could not check
649
+ * (npm: timeout after 2000ms)" or "no current version information" depending
650
+ * on whether the forced re-probe happened to return a failed status or simply
651
+ * never answered. Both are honest, but the operator reads them as two
652
+ * different problems, and neither states what matters after the full
653
+ * escalation: the answer is MISSING. A caller that escalated has waited, so it
654
+ * says so; the inline launcher path, which never escalated, keeps the more
655
+ * specific "could not check (reason)".
656
+ */
657
+ function asExhausted(status) {
658
+ if (!status || status.exhausted || status.state !== 'unknown')
659
+ return status;
660
+ return { ...status, exhausted: true };
661
+ }
662
+ /**
663
+ * Start the probe and expose the two moments described above. The first probe
664
+ * is started immediately; `quick` settles within the grace period and `settled`
665
+ * carries the whole escalation.
666
+ */
667
+ export function startStagedVersionStatus(options = {}) {
668
+ const { graceMs, finalMs, ...probeOptions } = options;
669
+ const grace = resolveGraceMs(graceMs);
670
+ const budget = resolveFinalTimeoutMs(finalMs, probeOptions.timeoutMs);
671
+ // `tracked` records that the FIRST probe reached a verdict of its own
672
+ // (including "the feature is off", which resolves immediately), so the
673
+ // escalation below can tell "no answer yet" from "nothing to report".
674
+ let firstSettled = false;
675
+ const first = startVersionStatusCheck({ ...probeOptions, timeoutMs: budget });
676
+ const tracked = first.then((value) => { firstSettled = true; return value; }, () => { firstSettled = true; return null; });
677
+ const quick = settleWithin(tracked, grace).then((r) => (r.hit ? r.value ?? null : null));
678
+ const settled = (async () => {
679
+ // 1) Landed during the top-of-command grace (or the cache answered).
680
+ const early = await settleWithin(tracked, grace);
681
+ if (early.hit)
682
+ return asExhausted(early.value ?? null);
683
+ // 2) End of the report: one more grace period for the in-flight probe.
684
+ const late = await settleWithin(tracked, grace);
685
+ if (late.hit)
686
+ return asExhausted(late.value ?? null);
687
+ // 3) Nothing yet. A disabled feature always resolves instantly, so
688
+ // still being in flight here means the probe is genuinely slow or
689
+ // the network is broken — ask once more, ignoring the throttle (a
690
+ // cached FAILURE would otherwise be re-reported for the whole
691
+ // retry backoff without a single request being made).
692
+ const retry = settleWithin(startVersionStatusCheck({ ...probeOptions, timeoutMs: budget, force: true }), budget);
693
+ const retried = await retry;
694
+ if (retried.hit) {
695
+ // A null here can only mean the feature was switched off between
696
+ // the two probes; honour it rather than inventing a verdict.
697
+ if (retried.value)
698
+ return asExhausted(retried.value);
699
+ if (firstSettled)
700
+ return null;
701
+ }
702
+ return buildExhaustedStatus(probeOptions.currentVersion ?? Config.VERSION, probeOptions.installKind || detectInstallKind(), probeOptions.cacheFile || PATHS.PROFILES.VERSION_CHECK_JSON, resolveReleaseSources({
703
+ ...(probeOptions.registryUrl !== undefined ? { registryUrl: probeOptions.registryUrl } : {}),
704
+ ...(probeOptions.githubReleaseUrl !== undefined ? { githubReleaseUrl: probeOptions.githubReleaseUrl } : {}),
705
+ }).map((s) => s.id), budget);
706
+ })().catch(() => null);
707
+ return { quick, settled };
363
708
  }
364
709
  //# sourceMappingURL=version_notice.js.map
package/dist/pm2.js CHANGED
@@ -98,7 +98,7 @@ import * as readline from 'node:readline';
98
98
  import { getErrorMessage } from './modules/utils/errors.js';
99
99
  import { isSameBotName } from './modules/utils/sanitize_key.js';
100
100
  import { muteChainLogs } from './modules/utils/chain_logs.js';
101
- import { startVersionStatusCheck, printVersionStatus } from './modules/version_notice.js';
101
+ import { startVersionStatusCheck, flushVersionStatusOrHeader } from './modules/version_notice.js';
102
102
  import { CLI_COLORS } from './modules/cli_colors.js';
103
103
  import { getStorage } from './modules/storage/index.js';
104
104
  import { usesAmaGridPrice } from './modules/dexbot_maintenance_runtime.js';
@@ -457,6 +457,10 @@ async function main({ botNameFilter = null, clawOnly = false, headless = false,
457
457
  }
458
458
  catch (error) {
459
459
  console.error(pm2Error(`\n❌ ${getErrorMessage(error)}`));
460
+ // Surface the version state on the failure path too: a start that dies
461
+ // here is exactly when the operator wants to know which build they are
462
+ // on and whether it is current, and the probe is already in flight.
463
+ await flushVersionStatusOrHeader(versionStatus);
460
464
  process.exit(1);
461
465
  }
462
466
  // Step 3: Generate ecosystem config
@@ -476,7 +480,10 @@ async function main({ botNameFilter = null, clawOnly = false, headless = false,
476
480
  console.log('If dexbot-cred stops, rerun `dexbot pm2` to unlock it again.');
477
481
  console.log('='.repeat(50));
478
482
  console.log();
479
- printVersionStatus(await versionStatus);
483
+ // The status line names the installed version; with the check switched off
484
+ // the shared helper falls back to the bare header, so `dexbot pm2` reports
485
+ // the running build exactly as `dexbot stat` does.
486
+ await flushVersionStatusOrHeader(versionStatus);
480
487
  }
481
488
  function startPM2Process(args, env = buildScopedChildEnv()) {
482
489
  return new Promise((resolve, reject) => {