dexterm-cli 0.1.1 → 0.1.3

package/dist/packages/data/src/intel/live-signals.js

@@ -0,0 +1,185 @@
+// dexterm — LIVE holder / rug SIGNALS engine (task-1404). Pure + deterministic.
+//
+// The token screen used to read holders and safety ONCE, when you opened it. This engine turns a stream of
+// repeated OBSERVATIONS of a token's holder/rug state into SIGNAL events — the changes worth telling a trader
+// about while the token is open or on the watchlist: a dev/creator sell, a top-holder / top-10 concentration
+// shift, LP removal or an unlock change, a mint/freeze authority flip, a new bundle / sniper cluster, a
+// fresh-wallet inflow, bonding-curve progress, a migration.
+//
+// Every signal is a RISK FLAG, never a certificate, and carries its SOURCE and the AGE of the data it read, with
+// an honest `stale` flag. No I/O, no clock, no randomness: the caller feeds `now` and already-fetched readings,
+// so a recording replays to the same signals and the tests can assert each one. Nothing here signs or trades.
+//
+// Baseline rule: a signal only fires on a comparison between two FRESH readings of the same field. A reading that
+// is stale (its panel kept the last value after a failed refresh, or it is older than `staleAfterMs`) updates the
+// latest-known value but never fires a signal off it — we cannot honestly timestamp a change we did not see land.
+// The first observation of a mint sets the baseline and fires nothing (so opening a token never floods).
+export const DEFAULT_SIGNAL_THRESHOLDS = {
+    devSellPct: 1,
+    concentrationPct: 3,
+    lpDropPct: 1,
+    liqDropFrac: 0.25,
+    bundlePct: 1,
+    sniperCount: 1,
+    freshPct: 5,
+    bondingStepPct: 5,
+    staleAfterMs: 60_000,
+};
+/** Every signal kind, for docs / UI / the alerts trigger catalogue. */
+export const SIGNAL_KINDS = [
+    'dev-sell', 'concentration', 'lp-unlock', 'liquidity', 'authority', 'bundle', 'sniper', 'fresh-wallet', 'bonding', 'migrated',
+];
+const CUMULATIVE = new Set(['bonding', 'bundled', 'snipers', 'fresh']);
+const r1 = (n) => Math.round(n * 10) / 10;
+export class LiveSignalsEngine {
+    thresholds;
+    state = new Map();
+    constructor(opts = {}) {
+        this.thresholds = { ...DEFAULT_SIGNAL_THRESHOLDS, ...opts.thresholds };
+    }
+    /** Whether a reading is too stale to fire a signal from (still updates the latest-known baseline). */
+    stale(reading, now) {
+        return reading.stale || now - reading.fetchedAt > this.thresholds.staleAfterMs;
+    }
+    /**
+     * Record one observation and return the signals it produced (empty for the first observation of a mint, or
+     * when nothing crossed a threshold). Baseline discipline (see module note):
+     *  - the first reading of a field sets the baseline and fires nothing;
+     *  - a STALE reading neither fires nor advances the baseline (so when it is fresh again we compare to the last
+     *    value we actually saw and never miss a change that happened while stale, nor fire off stale data);
+     *  - a fresh LEVEL field (dev / top10 / lpLocked / liq / authorities) is compared to the previous value and the
+     *    baseline then advances to the current value;
+     *  - a fresh CUMULATIVE field (bonding / bundled / snipers / fresh) advances its baseline ONLY when it fires, so
+     *    gradual drift between fast pushes accumulates until it crosses the threshold instead of being lost.
+     */
+    observe(obs) {
+        const t = this.thresholds;
+        const now = obs.at;
+        const prev = this.state.get(obs.mint) ?? { latest: {}, latestBool: {}, anchor: {} };
+        const next = { latest: { ...prev.latest }, latestBool: { ...prev.latestBool }, anchor: { ...prev.anchor } };
+        const out = [];
+        const mk = (kind, level, title, text, reading, value, delta) => {
+            out.push({ kind, mint: obs.mint, level, title, text, source: reading.source, dataAgeMs: Math.max(0, now - reading.fetchedAt), stale: false, value, delta, at: now });
+            return true;
+        };
+        const num = (key, reading, fire) => {
+            if (!reading || reading.value === null || !Number.isFinite(reading.value))
+                return;
+            const cur = reading.value;
+            const prevLatest = prev.latest[key];
+            const state = { value: cur, source: reading.source, fetchedAt: reading.fetchedAt };
+            const cumulative = CUMULATIVE.has(key);
+            if (!prevLatest) {
+                next.latest[key] = state;
+                if (cumulative)
+                    next.anchor[key] = cur;
+                return;
+            } // first: baseline only
+            if (this.stale(reading, now))
+                return; // stale: keep the last fresh value, fire nothing, do not advance
+            next.latest[key] = state; // latest always tracks the newest fresh value
+            const anchor = cumulative ? (prev.anchor[key] ?? prevLatest.value) : prevLatest.value;
+            const fired = fire(anchor, cur, reading) === true;
+            if (cumulative && fired)
+                next.anchor[key] = cur; // cumulative anchor advances only when a signal fires
+        };
+        num('dev', obs.dev, (was, cur, reading) => was - cur >= t.devSellPct && mk('dev-sell', 'warn', 'dev sold', `creator sold — dev holding ${r1(was)}% → ${r1(cur)}%`, reading, r1(cur), r1(cur - was)));
+        num('top10', obs.top10, (was, cur, reading) => {
+            const d = cur - was;
+            return Math.abs(d) >= t.concentrationPct && mk('concentration', d > 0 ? 'warn' : 'info', d > 0 ? 'top-10 up' : 'top-10 down', `top-10 concentration ${r1(was)}% → ${r1(cur)}% (pools excluded)`, reading, r1(cur), r1(d));
+        });
+        num('lpLocked', obs.lpLocked, (was, cur, reading) => was - cur >= t.lpDropPct && mk('lp-unlock', 'down', 'LP unlocked', `LP locked dropped ${r1(was)}% → ${r1(cur)}%`, reading, r1(cur), r1(cur - was)));
+        num('liq', obs.liq, (was, cur, reading) => {
+            if (was > 0 && cur < was && (was - cur) / was >= t.liqDropFrac) {
+                const pct = Math.round(((was - cur) / was) * 100);
+                return mk('liquidity', 'down', 'liquidity fell', `liquidity fell ~${pct}% ($${fmtUsd(was)} → $${fmtUsd(cur)})`, reading, Math.round(cur), Math.round(cur - was));
+            }
+            return false;
+        });
+        num('bundled', obs.bundled, (was, cur, reading) => cur - was >= t.bundlePct && mk('bundle', 'warn', 'bundle up', `bundled supply ${r1(was)}% → ${r1(cur)}% of the top sample`, reading, r1(cur), r1(cur - was)));
+        num('snipers', obs.snipers, (was, cur, reading) => cur - was >= t.sniperCount && mk('sniper', 'warn', 'snipers up', `snipers ${Math.round(was)} → ${Math.round(cur)} in the launch window`, reading, Math.round(cur), Math.round(cur - was)));
+        num('fresh', obs.fresh, (was, cur, reading) => cur - was >= t.freshPct && mk('fresh-wallet', 'warn', 'fresh wallets', `fresh-at-buy wallets ${r1(was)}% → ${r1(cur)}% of the top sample`, reading, r1(cur), r1(cur - was)));
+        num('cluster', obs.cluster, () => false); // tracked for the rules field only; concentration covers the UI
+        num('bonding', obs.bonding, (was, cur, reading) => cur - was >= t.bondingStepPct && mk('bonding', 'info', 'bonding', `bonding curve ${r1(was)}% → ${r1(cur)}%`, reading, r1(cur), r1(cur - was)));
+        // --- authorities: a false→true flip is the risk (minting / freezing re-enabled); true→false is good news.
+        const auth = (key, reading, label, risk) => {
+            if (!reading || reading.present === null)
+                return;
+            const cur = reading.present;
+            const was = prev.latestBool[key];
+            const state = { value: cur, source: reading.source, fetchedAt: reading.fetchedAt };
+            if (!was) {
+                next.latestBool[key] = state;
+                return;
+            }
+            if (this.stale(reading, now))
+                return;
+            if (was.value !== cur) {
+                if (cur)
+                    mk('authority', 'warn', `${label} on`, `${label} re-enabled — ${risk}`, reading, 1, 1);
+                else
+                    mk('authority', 'up', `${label} revoked`, `${label} revoked`, reading, 0, -1);
+            }
+            next.latestBool[key] = state;
+        };
+        auth('mintAuth', obs.mintAuth, 'mint authority', 'new supply can be minted');
+        auth('freezeAuth', obs.freezeAuth, 'freeze authority', 'transfers can be frozen');
+        // --- migration: once, on the false→true flip.
+        if (obs.migrated && obs.migrated.value !== null) {
+            const cur = obs.migrated.value;
+            const was = prev.latestBool.migrated;
+            const state = { value: cur, source: obs.migrated.source, fetchedAt: obs.migrated.fetchedAt };
+            if (!was) {
+                next.latestBool.migrated = state;
+            }
+            else if (!this.stale(obs.migrated, now)) {
+                if (!was.value && cur)
+                    mk('migrated', 'info', 'migrated', 'migrated to a DEX pool — bonding curve closed', obs.migrated, 1, 1);
+                next.latestBool.migrated = state;
+            }
+        }
+        this.state.set(obs.mint, next);
+        return out;
+    }
+    /** The latest-known numeric fields for a mint, for the rules engine (null when never observed). */
+    fields(mint) {
+        const s = this.state.get(mint);
+        const n = (x) => (x ? x.value : null);
+        const b = (x) => (x ? (x.value ? 1 : 0) : null);
+        return {
+            top10: n(s?.latest.top10), dev: n(s?.latest.dev), bundled: n(s?.latest.bundled), snipers: n(s?.latest.snipers), fresh: n(s?.latest.fresh),
+            cluster: n(s?.latest.cluster), lpLocked: n(s?.latest.lpLocked), bonding: n(s?.latest.bonding),
+            mintable: b(s?.latestBool.mintAuth), freezable: b(s?.latestBool.freezeAuth),
+        };
+    }
+    /** A per-field snapshot with age + stale for the UI (null source = never observed). */
+    snapshot(mint, now) {
+        const s = this.state.get(mint);
+        const fromNum = (x) => this.snap(x, now);
+        const fromBool = (x) => (x ? { value: x.value ? 1 : 0, source: x.source, ageMs: Math.max(0, now - x.fetchedAt), stale: now - x.fetchedAt > this.thresholds.staleAfterMs } : { value: null, source: null, ageMs: null, stale: false });
+        return {
+            top10: fromNum(s?.latest.top10), dev: fromNum(s?.latest.dev), bundled: fromNum(s?.latest.bundled), snipers: fromNum(s?.latest.snipers),
+            fresh: fromNum(s?.latest.fresh), cluster: fromNum(s?.latest.cluster), lpLocked: fromNum(s?.latest.lpLocked), bonding: fromNum(s?.latest.bonding),
+            liq: fromNum(s?.latest.liq), mintable: fromBool(s?.latestBool.mintAuth), freezable: fromBool(s?.latestBool.freezeAuth), migrated: fromBool(s?.latestBool.migrated),
+        };
+    }
+    snap(x, now) {
+        if (!x)
+            return { value: null, source: null, ageMs: null, stale: false };
+        return { value: x.value, source: x.source, ageMs: Math.max(0, now - x.fetchedAt), stale: now - x.fetchedAt > this.thresholds.staleAfterMs };
+    }
+    /** Drop a mint's baseline (closed token the UI no longer tracks). */
+    forget(mint) { this.state.delete(mint); }
+    /** Known mints (for hygiene / tests). */
+    tracked() { return [...this.state.keys()]; }
+}
+function fmtUsd(n) {
+    const a = Math.abs(n);
+    if (a >= 1e9)
+        return `${r1(n / 1e9)}B`;
+    if (a >= 1e6)
+        return `${r1(n / 1e6)}M`;
+    if (a >= 1e3)
+        return `${r1(n / 1e3)}K`;
+    return String(Math.round(n));
+}

package/dist/packages/data/src/larp/link-baseline.js

@@ -0,0 +1,196 @@
+// LARP check — links-only baseline grade (task-1401). Pure, offline, deterministic.
+//
+// The LARP check (skill `larp-check`) judges a coin's product from fetched pages, the domain and GitHub. That
+// model stage cannot be replayed on history: the pages are gone or have changed since. What CAN be replayed is
+// the part of the evidence the recorder keeps point-in-time: the website / X / Telegram links a coin advertised
+// (DexScreener `info` + Jupiter metadata, the same fields `get_links` reads). This module turns those three links
+// into named signals and a baseline grade, so the same function scores the backtest eval set and the live
+// `get_links` result the skill starts from.
+//
+// What the grade is: a RISK FLAG from link shape alone, never a verdict on the product. It uses only the skill's
+// verdict names it can honestly reach: `LARP` (the link shape contradicts a product claim: a social or launchpad
+// page posing as the website, a placeholder host, a tweet instead of an account), `UNVERIFIABLE` (no website at
+// all, nothing to vet) and `EARLY_BUT_REAL` (an own-domain site with nothing contradicting it). It never says
+// `REAL_PRODUCT`: links alone cannot show a reachable product. Weights are tuned on the TRAIN split of the
+// recorded eval set only (packages/packs/eval/README.md); the measured test-split numbers ship with the rubric.
+import { parseHttpUrl } from "./links.js";
+/** The named signals a rubric weighs. All are LARP-direction (a weight > 0 pushes toward `LARP`). */
+export const LINK_SIGNALS = [
+    'site_is_social', 'site_is_launchpad', 'site_linktree', 'site_free_host', 'site_no_name_match',
+    'cheap_tld', 'x_not_profile', 'no_x', 'no_tg',
+];
+/**
+ * v0: the pre-tuning rubric, written from the larp-check skill text BEFORE any backtest (task-1401): a social or
+ * launchpad page posing as the website and a tweet/community link instead of an account are the link-visible
+ * LARP signals the skill names; a placeholder host, a link hub, and a site whose domain does not name the coin
+ * count one point each. This is the "before" the tuned rubric is compared with.
+ */
+export const LINK_RUBRIC_V0 = {
+    id: 'larp-links-v0',
+    weights: { site_is_social: 2, site_is_launchpad: 2, site_linktree: 1, site_free_host: 1, site_no_name_match: 1, cheap_tld: 0, x_not_profile: 1, no_x: 0, no_tg: 0 },
+    threshold: 2,
+    provenance: 'hand-written from the larp-check skill text before the backtest (task-1401)',
+};
+/**
+ * v1: tuned on the TRAIN split of packages/packs/eval/skills-eval.json (grid search over weights 0..2 and
+ * threshold 1..5, objective MCC of LARP→bad, ties to the smaller weight sum). Test-split numbers:
+ * packages/packs/eval/skills-backtest.json. Regenerate with `dexterm backtest --subject skills --tune`.
+ */
+export const LINK_RUBRIC_V1 = {
+    id: 'larp-links-v1',
+    weights: { site_is_social: 0, site_is_launchpad: 0, site_linktree: 0, site_free_host: 1, site_no_name_match: 1, cheap_tld: 1, x_not_profile: 2, no_x: 1, no_tg: 1 },
+    threshold: 4,
+    provenance: 'tuned on the train split of the task-1401 eval set (see packages/packs/eval/README.md)',
+};
+/**
+ * The held-out TEST-split counts for LINK_RUBRIC_V1 (packages/packs/eval/skills-backtest.json `larp.after.test`).
+ * A test asserts these match the committed report, so a re-tune cannot ship stale numbers.
+ */
+export const LINK_RUBRIC_MEASURED = {
+    rubric: 'larp-links-v1',
+    eval: 'task-1401 eval set, 2026-10-16',
+    horizon: '72h',
+    test: {
+        n: 328, bad: 61,
+        by_grade: { LARP: { n: 14, bad: 4 }, UNVERIFIABLE: { n: 130, bad: 38 }, EARLY_BUT_REAL: { n: 184, bad: 19 } },
+    },
+};
+/** The rubric the live `get_links` baseline uses. */
+export const DEFAULT_LINK_RUBRIC = LINK_RUBRIC_V1;
+const SOCIAL_HOSTS = new Set([
+    'x.com', 'twitter.com', 'mobile.twitter.com', 't.me', 'telegram.me', 'telegram.dog', 'discord.gg', 'discord.com',
+    'discordapp.com', 'instagram.com', 'tiktok.com', 'youtube.com', 'm.youtube.com', 'youtu.be', 'facebook.com', 'fb.com',
+    'reddit.com', 'threads.net', 'warpcast.com', 'truthsocial.com', 'kick.com', 'twitch.tv',
+]);
+const LAUNCHPAD_HOSTS = new Set([
+    'pump.fun', 'dexscreener.com', 'birdeye.so', 'solscan.io', 'jup.ag', 'raydium.io', 'meteora.ag', 'letsbonk.fun',
+    'bonk.fun', 'moonshot.money', 'believe.app', 'bags.fm', 'gmgn.ai', 'axiom.trade', 'dextools.io', 'coingecko.com',
+    'coinmarketcap.com', 'photon-sol.tinyastro.io', 'geckoterminal.com', 'rugcheck.xyz', 'solana.fm', 'heaven.xyz',
+]);
+const LINKHUB_HOSTS = new Set(['linktr.ee', 'linktree.com', 'link3.to', 'bio.link', 'beacons.ai', 'campsite.bio', 'solo.to', 'lnk.bio', 'hoo.be', 'allmylinks.com']);
+const FREE_HOST_SUFFIXES = [
+    'vercel.app', 'netlify.app', 'github.io', 'carrd.co', 'wixsite.com', 'webflow.io', 'framer.website', 'framer.app',
+    'framer.ai', 'notion.site', 'gitbook.io', 'substack.com', 'pages.dev', 'web.app', 'firebaseapp.com', 'herokuapp.com',
+    'replit.app', 'repl.co', 'glitch.me', 'weebly.com', 'wordpress.com', 'blogspot.com', 'mystrikingly.com',
+    'godaddysites.com', 'squarespace.com', 'medium.com', 'durable.co', 'lovable.app', 'onrender.com', 'surge.sh',
+    'webnode.page', 'site123.me', 'tilda.ws', 'super.site', 'my.canva.site', 'canva.site', 'bolt.host', 'netlify.com',
+];
+const FREE_HOST_EXACT = new Set(['sites.google.com', 'docs.google.com', 'drive.google.com', 'telegra.ph', 'pastebin.com', 'medium.com']);
+const CHEAP_TLDS = new Set(['fun', 'xyz', 'lol', 'meme', 'site', 'online', 'club', 'top', 'vip', 'wtf', 'space', 'icu', 'buzz', 'cfd', 'sbs', 'click', 'live', 'world', 'today', 'pw', 'cc', 'monster', 'rest', 'bond', 'cyou']);
+const X_RESERVED = new Set(['home', 'search', 'explore', 'i', 'hashtag', 'intent', 'share', 'messages', 'notifications', 'settings', 'compose']);
+const hostOf = (u) => u.hostname.toLowerCase().replace(/^www\./, '').replace(/\.$/, '');
+const endsWithHost = (host, suffix) => host === suffix || host.endsWith(`.${suffix}`);
+const norm = (s) => s.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]/g, '');
+function webKind(raw) {
+    if (raw === null || raw === undefined || String(raw).trim() === '')
+        return { kind: 'none', url: null };
+    const u = parseHttpUrl(raw);
+    if (!u)
+        return { kind: 'invalid', url: null };
+    const host = hostOf(u);
+    if ([...SOCIAL_HOSTS].some((h) => endsWithHost(host, h)))
+        return { kind: 'social', url: u };
+    if ([...LAUNCHPAD_HOSTS].some((h) => endsWithHost(host, h)))
+        return { kind: 'launchpad', url: u };
+    if (LINKHUB_HOSTS.has(host))
+        return { kind: 'linktree', url: u };
+    if (FREE_HOST_EXACT.has(host) || FREE_HOST_SUFFIXES.some((s) => host.endsWith(`.${s}`)))
+        return { kind: 'free-host', url: u };
+    return { kind: 'own-domain', url: u };
+}
+function xKind(raw) {
+    if (raw === null || raw === undefined || String(raw).trim() === '')
+        return 'none';
+    const u = parseHttpUrl(raw);
+    if (!u)
+        return 'other';
+    const host = hostOf(u);
+    if (!['x.com', 'twitter.com', 'mobile.twitter.com'].includes(host))
+        return 'other';
+    const parts = u.pathname.split('/').filter(Boolean).map((p) => p.toLowerCase());
+    if (parts[0] === 'i' && parts[1] === 'communities')
+        return 'community';
+    if (!parts.length || X_RESERVED.has(parts[0]))
+        return 'other';
+    if (parts[1] === 'status' || parts[1] === 'statuses')
+        return 'status';
+    if (parts.length === 1 && /^[a-z0-9_]{1,15}$/.test(parts[0]))
+        return 'profile';
+    return 'other';
+}
+/** Does the site's domain carry the token's symbol or name? Symbol ≥ 3 chars, name compacted or a ≥ 4-char word. */
+function domainMatches(u, symbol, name) {
+    const sym = norm(String(symbol ?? '').replace(/^\$/, ''));
+    const nm = norm(String(name ?? ''));
+    const words = String(name ?? '').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 4);
+    if (!sym && !nm)
+        return null;
+    const host = hostOf(u);
+    const labels = host.split('.');
+    const body = norm(labels.length > 1 ? labels.slice(0, -1).join('') : host);
+    if (!body)
+        return false;
+    if (sym.length >= 3 && body.includes(sym))
+        return true;
+    if (nm.length >= 3 && body.includes(nm))
+        return true;
+    return words.some((w) => body.includes(norm(w)));
+}
+/**
+ * Derive the URL-free features from the three primary links (the store's merge: Jupiter first, then DexScreener's
+ * first website / first X / first Telegram). `symbol`/`name` enable the domain-match signal; they are not kept.
+ */
+export function linkFeatures(input) {
+    const w = webKind(input.web);
+    return {
+        web: w.kind,
+        x: xKind(input.x),
+        tg: !!(input.tg && String(input.tg).trim()),
+        webMatchesToken: w.url && (w.kind === 'own-domain' || w.kind === 'free-host') ? domainMatches(w.url, input.symbol, input.name) : null,
+        cheapTld: w.url && w.kind === 'own-domain' ? CHEAP_TLDS.has(hostOf(w.url).split('.').pop() ?? '') : null,
+    };
+}
+/** The signals present in a feature set. */
+export function linkSignals(f) {
+    const s = [];
+    if (f.web === 'social')
+        s.push('site_is_social');
+    if (f.web === 'launchpad')
+        s.push('site_is_launchpad');
+    if (f.web === 'linktree')
+        s.push('site_linktree');
+    if (f.web === 'free-host' || f.web === 'invalid')
+        s.push('site_free_host');
+    if (f.webMatchesToken === false)
+        s.push('site_no_name_match');
+    if (f.cheapTld === true)
+        s.push('cheap_tld');
+    if (f.x === 'status' || f.x === 'community' || f.x === 'other')
+        s.push('x_not_profile');
+    if (f.x === 'none')
+        s.push('no_x');
+    if (!f.tg)
+        s.push('no_tg');
+    return s;
+}
+/** Grade one coin's links with a rubric. No website at all is `UNVERIFIABLE` (fixed rule, never tuned). */
+export function gradeLinks(f, rubric = DEFAULT_LINK_RUBRIC) {
+    const signals = linkSignals(f);
+    const score = signals.reduce((a, s) => a + (rubric.weights[s] ?? 0), 0);
+    const grade = f.web === 'none' ? 'UNVERIFIABLE' : score >= rubric.threshold ? 'LARP' : 'EARLY_BUT_REAL';
+    return { rubric: rubric.id, grade, score, signals };
+}
+/**
+ * The store's primary-link merge (packages/data/src/store.ts: Jupiter first, then DexScreener), so the live
+ * baseline reads the same three links the recorder's cache holds for the eval set.
+ */
+export function primaryLinks(src) {
+    const info = src.dexscreener?.info;
+    const dsX = info?.socials?.find((s) => s?.type === 'twitter' || s?.type === 'x')?.url ?? null;
+    const dsTg = info?.socials?.find((s) => s?.type === 'telegram')?.url ?? null;
+    return {
+        web: src.jupiter?.website ?? info?.websites?.[0]?.url ?? null,
+        x: src.jupiter?.twitter ?? dsX,
+        tg: src.jupiter?.telegram ?? dsTg,
+    };
+}

package/dist/packages/data/src/sources/dexscreener.js

@@ -126,6 +126,20 @@ export class DexScreener {
         }
         return out;
     }
+    /**
+     * task-1401: the coin a pair (pool) trades. A dexscreener.com/solana/<address> link usually names the POOL, not
+     * the mint, so a pasted link is resolved here before the token screen opens. Null when DexScreener has no Solana
+     * pair at that address (the caller then treats it as a mint). The side that is not wrapped SOL wins.
+     */
+    async pairCoin(pairAddress) {
+        const r = await this.http.getJson(`${this.base}/latest/dex/pairs/${CHAIN}/${encodeURIComponent(pairAddress)}`, FAST);
+        const list = r.data?.pairs ?? (r.data?.pair ? [r.data.pair] : []);
+        const p = (Array.isArray(list) ? list : []).find((x) => x?.chainId === CHAIN && x.pairAddress === pairAddress);
+        if (!p)
+            return null;
+        const WSOL = 'So11111111111111111111111111111111111111112';
+        return p.baseToken?.address === WSOL && p.quoteToken?.address ? p.quoteToken.address : p.baseToken?.address ?? null;
+    }
     async tokenPairs(mint) {
         const r = await this.http.getJson(`${this.base}/token-pairs/v1/${CHAIN}/${mint}`, FAST);
         return (Array.isArray(r.data) ? r.data : []).filter((p) => p.chainId === CHAIN).map((p) => normalizePair(p, r.fetchedAt));

package/dist/packages/data/src/sources/pumpportal.js

@@ -240,7 +240,12 @@ export class PumpPortalClient {
             if (speed > 0 && m.tMs > last)
                 await this.clock.sleep((m.tMs - last) / speed);
             last = m.tMs;
-            this.handle(m.text, this.clock.now());
+            // Anchor each message's receive time to the recording's own `tMs` offset, not `clock.now()`. Reading the
+            // live clock per message makes `receivedAt` (and the row's `createdAt`) depend on where real-time
+            // millisecond boundaries happen to fall inside this synchronous loop, so the newest-first row order
+            // flipped between runs — a Node-22 CI flake in the new-pairs replay test (task-1394). Offsets from one
+            // clock read are monotonic and deterministic, so replay now sorts identically on every run and engine.
+            this.handle(m.text, this.startedAt + m.tMs);
         }
         return rec.messages.length;
     }

package/dist/packages/data/src/trade/copy/index.js

@@ -2,7 +2,7 @@
 // capped auto-mirror copy mandate (Tier 3). Personal, self-directed, non-custodial; paper/devnet only; nothing
 // here signs, holds a key, or arms anything without the plan engine's own keypress gate.
 export { SOL_LEG_MIN_LAMPORTS, tokenDeltasForOwner, lamportsDeltaFor, decodeTx, decodeWalletTrades } from "./trades.js";
-export { WIN_RATE_MIN_N, positionsOf, earlyEntryScore, walletStats } from "./stats.js";
+export { WIN_RATE_MIN_N, positionsOf, earlyEntryScore, walletStats, fmtHoldMs } from "./stats.js";
 export { FOLLOW_NAME_MAX, FOLLOWS_MAX, defaultFollowsPath, isWalletAddress, cleanFollowName, FollowStore, shortAddr } from "./follows.js";
 export { WalletTracker, TRACKER_DEFAULTS } from "./tracker.js";
 export { MIRROR_LIMITS, leaderFillPriceUsd, buildMirror, leaderSoldSince } from "./mirror.js";

package/dist/packages/data/src/trade/copy/stats.js

@@ -17,12 +17,13 @@ export function positionsOf(trades) {
         const delta = BigInt(tr.tokenDelta);
         let p = pos.get(tr.mint);
         if (!p) {
-            p = { mint: tr.mint, tokensRaw: 0n, peakRaw: 0n, costSol: 0, realisedSol: 0, buys: 0, sells: 0, transfers: 0, flagged: false, closed: false, firstT: tr.t, lastT: tr.t };
+            p = { mint: tr.mint, tokensRaw: 0n, peakRaw: 0n, costSol: 0, realisedSol: 0, buys: 0, sells: 0, transfers: 0, flagged: false, closed: false, firstT: tr.t, lastT: tr.t, firstKnown: tr.tKnown, lastKnown: tr.tKnown, holdMs: null };
             pos.set(tr.mint, p);
         }
         const L = lots.get(tr.mint) ?? [];
         lots.set(tr.mint, L);
         p.lastT = tr.t;
+        p.lastKnown = tr.tKnown;
         if (delta > 0n) {
             // a buy with a SOL leg carries cost; a token-swap leg or an airdrop is cost 0 and flagged
             const cost = tr.side === 'buy' && tr.solDelta !== null ? Math.abs(tr.solDelta) : 0;
@@ -76,8 +77,34 @@ export function positionsOf(trades) {
         }
         p.closed = closedNow(p);
     }
+    // hold time = first buy → last sell, only trustworthy for a CLOSED position whose first+last block times are both real
+    for (const p of pos.values())
+        p.holdMs = p.closed && p.firstKnown && p.lastKnown && p.lastT > p.firstT ? p.lastT - p.firstT : null;
     return [...pos.values()].sort((a, b) => b.lastT - a.lastT);
 }
+/** Compact human hold time: 45s · 12m · 3.2h · 2.1d. null → '—'. */
+export function fmtHoldMs(ms) {
+    if (ms === null)
+        return '—';
+    const s = ms / 1000;
+    if (s < 90)
+        return `${Math.round(s)}s`;
+    const m = s / 60;
+    if (m < 90)
+        return `${Math.round(m)}m`;
+    const h = m / 60;
+    if (h < 48)
+        return `${h.toFixed(1)}h`;
+    return `${(h / 24).toFixed(1)}d`;
+}
+/** Median over the numbers (already finite); undefined on an empty list. */
+function median(xs) {
+    if (!xs.length)
+        return undefined;
+    const s = [...xs].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
 /** Early-entry score = median over tokens of (1 − rank / buyers); null without ranks (design §4.3). */
 export function earlyEntryScore(inputs) {
     const xs = inputs.filter((e) => e.buyers > 0 && e.rank >= 0 && e.rank < e.buyers).map((e) => 1 - e.rank / e.buyers).sort((a, b) => a - b);
@@ -96,6 +123,11 @@ export function walletStats(wallet, trades, opts = {}) {
     const ts = trades.map((t) => t.t).filter((t) => t > 0);
     const winRate = closed.length >= WIN_RATE_MIN_N ? wins / closed.length : null;
     const txs = opts.txs ?? new Set(trades.map((t) => t.sig)).size;
+    const holds = closed.map((p) => p.holdMs).filter((m) => m !== null);
+    const holdMedianMs = median(holds) ?? null;
+    const holdNote = holdMedianMs === null
+        ? (closed.length ? `no closed position with both block times known (${closed.length} closed)` : 'no closed positions yet')
+        : `median first-buy→last-sell over ${holds.length} closed position${holds.length === 1 ? '' : 's'} with known times`;
     return {
         wallet,
         trades: trades.length,
@@ -112,9 +144,11 @@ export function walletStats(wallet, trades, opts = {}) {
         winRateNote: closed.length >= WIN_RATE_MIN_N ? `${wins}/${closed.length} closed` : `hidden under n=${WIN_RATE_MIN_N} (${wins}/${closed.length} closed so far)`,
         open: positions.length - closed.length,
         earlyEntry: earlyEntryScore(opts.earlyEntry ?? []),
+        holdMedianMs,
+        holdNote,
         positions,
         firstT: ts.length ? Math.min(...ts) : null,
         lastT: ts.length ? Math.max(...ts) : null,
-        sample: { txs, complete: !!opts.complete, note: opts.complete ? `all ${txs} txs` : `last ${txs} txs only · older history not fetched` },
+        sample: { txs, complete: !!opts.complete, note: opts.complete ? `all ${txs} txs` : `last ${txs} txs only · older history not fetched`, source: 'helius-history', asOf: opts.asOf ?? null },
     };
 }

package/dist/packages/data/src/trade/copy/tracker.js

@@ -63,7 +63,7 @@ export class WalletTracker {
     alerts(limit = 50) { return this.alertLog.slice(-limit).reverse(); }
     stats(addr) {
         const w = this.wallets.get(addr);
-        return walletStats(addr, w?.trades ?? [], { solUsd: this.solUsd(), txs: w?.txs ?? 0, complete: w?.complete ?? false, earlyEntry: this.earlyEntry(addr) });
+        return walletStats(addr, w?.trades ?? [], { solUsd: this.solUsd(), txs: w?.txs ?? 0, complete: w?.complete ?? false, earlyEntry: this.earlyEntry(addr), asOf: w?.asOf ?? null });
     }
     /** Per-wallet poll error (shown on the row), null when the last poll was clean. */
     walletError(addr) { return this.wallets.get(addr)?.error ?? null; }
@@ -89,11 +89,12 @@ export class WalletTracker {
         for (const f of this.follows.list()) {
             let w = this.wallets.get(f.addr);
             if (!w) {
-                w = { primed: false, seen: new Set(), trades: [], txs: 0, complete: false, lastSlot: 0, error: null };
+                w = { primed: false, seen: new Set(), trades: [], txs: 0, complete: false, lastSlot: 0, error: null, asOf: null };
                 this.wallets.set(f.addr, w);
             }
             try {
                 const page = await this.history.transactions(f.addr, { limit: w.primed ? this.pageLimit : this.backfillLimit, sortOrder: 'desc' });
+                w.asOf = page.fetchedAt;
                 const fresh = page.data.filter((tx) => { const s = tx.transaction?.signatures?.[0]; return !!s && !w.seen.has(s); });
                 for (const tx of fresh)
                     w.seen.add(tx.transaction.signatures[0]);

package/dist/packages/mcp/assets/kb/app-help/app-help-command.md

@@ -0,0 +1,35 @@
+---
+id: app-help-command
+title: Get help on how dexterm works (dexterm help)
+kind: app-help
+screen: all
+feature: app-help
+tags:
+  - app-help
+  - help
+  - how
+  - topic
+  - topics
+  - guide
+  - manual
+  - docs
+  - commands
+commands:
+  - help
+flags:
+  - --help
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+`dexterm help [topic]` answers "how do I ..." from the generated app-help knowledge base — the same entries the analyst's `app_help` tool uses, so they cannot drift from the app. `dexterm help` lists the topics; `dexterm help <topic|key|command>` prints the matching entry with the exact key or command. `--help` (or `-h`) on any command prints its usage. The analyst searches app-help first and never invents a key.
+
+CLI: `dexterm help`.

package/dist/packages/mcp/assets/kb/app-help/ask-the-analyst.md

@@ -0,0 +1,43 @@
+---
+id: ask-the-analyst
+title: Ask the analyst a question
+kind: app-help
+screen: analyst
+feature: analyst
+tags:
+  - app-help
+  - analyst
+  - ask
+  - claude
+  - ai
+  - question
+  - dossier
+  - chat
+keys:
+  - a
+  - enter
+actions:
+  - analyst.toggle
+  - open
+flags:
+  - --no-ai
+tools:
+  - get_dossier
+  - kb_search
+  - app_help
+  - case_lookup
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+The analyst is your own `claude` login. ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.
+
+Keys: `a`, `⏎` (screener).

package/dist/packages/mcp/assets/kb/app-help/backtest.md

@@ -0,0 +1,33 @@
+---
+id: backtest
+title: Backtest the rug model or skills
+kind: app-help
+screen: all
+feature: skill-backtest
+tags:
+  - app-help
+  - backtest
+  - eval
+  - accuracy
+  - model
+  - metrics
+  - history
+commands:
+  - backtest
+tools:
+  - rug_backtest
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+`dexterm backtest --subject heuristic|skills|larp|pack_verdicts` scores a subject against the recorder's outcome-labelled history and prints honest metrics (precision/recall, Brier vs base rate, AUC, calibration) with leakage checks. With no labelled outcomes it says so and prints no metrics rather than fabricating any.
+
+CLI: `dexterm backtest`.