dexterm-cli 0.2.0 → 0.2.2

package/dist/packages/cli/src/record-cmd.js

@@ -1,3 +1,11 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 // dexterm — `dexterm record` (task-1414): a HEADLESS collector that keeps the history recorder fed when
 // nobody has the TUI open. The recorder (task-1329) only grows while the interactive app runs; the backtest
 // (task-1401) is only worth re-running on fresh data, so this command runs the exact same recorder jobs
@@ -20,13 +28,17 @@
 // re-installed with them: `--retention-mb N` replaces that pause with eviction of the oldest history (observation
 // never pauses), `--retention-days D` is the age rule for snapshot rows, and `--focus-ticks` runs the autotrade
 // tick lane (5–10 s DexScreener samples of watchlist / held / candidate / open coins, plus 1m candles).
+// task-1786 (winner-recall DATA-GAPS items 1-2), opt-in the same way: `--focus-module PATH` loads an ESM module whose
+// `focus(now)` adds focus coins to the tick lane (the challenge / control coins live outside the app; the module that
+// reads them lives with them), and `--exit-probes` adds a keyless Jupiter sell quote for every held focus coin once a
+// minute (exit-probes.ts). Both imply --focus-ticks.
 import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { defaultDbPath, resolveRpcUrl, extraRpcUrls, redactSecrets } from '../../data/src/index.js';
 import { PumpPortalClient } from '../../data/src/index.js';
-import { Recorder, recorderEnabled, dbFocus, focusFilePath, readFocusFile, DEFAULT_TICKS } from '../../recorder/src/index.js';
+import { Recorder, recorderEnabled, dbFocus, focusFilePath, readFocusFile, exitProbeDeps, DEFAULT_TICKS } from '../../recorder/src/index.js';
 import { dextermHome } from "./boot-state.js";
 import { createLiveFeed } from "./feed.js";
 import { NewPairsLive } from "./live/index.js";
@@ -50,13 +62,30 @@ export function buildLiveEngine(env, opts) {
     // Focus coins for the tick lane: the watchlist + paper positions in this DB, and whatever the autotrade runner /
     // the app publish in the focus file. Read on every poll (two indexed reads + one small file).
     const focusFile = focusFilePath(dextermHome(env));
+    // task-1786: the focus module's coins. A throwing module costs its own coins only (logged at most every 10 min).
+    let extraFailedAt = -Infinity;
+    const extra = () => {
+        if (!opts.extraFocus)
+            return [];
+        try {
+            return [...opts.extraFocus()];
+        }
+        catch (e) {
+            if (Date.now() - extraFailedAt > 600_000) {
+                extraFailedAt = Date.now();
+                opts.onLog?.(`record: focus module failed: ${redactSecrets(e.message)}\n`);
+            }
+            return [];
+        }
+    };
     const recorder = new Recorder({
         path: opts.dbPath, onLog: opts.verbose ? opts.onLog : undefined,
         // The cap reclaims the data layer's expired cache entries (its own rule: a day past their TTL) before it evicts
         // any history; `feed` is built above, so the hook can reach it.
         ...(opts.retentionBytes ? { cap: { maxBytes: opts.retentionBytes, reclaim: () => feed.dl.cache.prune() } } : {}),
         ...(opts.retentionDays ? { retention: { columnsDays: opts.retentionDays } } : {}),
-        ...(opts.focusTicks ? { ticks: { focus: () => [...dbFocus(recorder.database), ...readFocusFile(focusFile, Date.now())] } } : {}),
+        ...(opts.focusTicks ? { ticks: { focus: () => [...dbFocus(recorder.database), ...readFocusFile(focusFile, Date.now()), ...extra()] } } : {}),
+        ...(opts.focusTicks && opts.exitProbes ? { exitProbes: {} } : {}),
     });
     recorder.attach(feed.dl.store);
     let newpairs = null;
@@ -71,6 +100,7 @@ export function buildLiveEngine(env, opts) {
         feed.extraMints = () => [...np.rows.keys()];
     }
     const dl = feed.dl;
+    const probeDeps = exitProbeDeps(dl);
     return {
         async observe() {
             const before = recorder.counters.written;
@@ -83,7 +113,14 @@ export function buildLiveEngine(env, opts) {
         }
         catch { /* logged inside; never fatal */ } },
         enforceCap() { return recorder.enforceCap(); },
-        ...(opts.focusTicks ? { pollTicks: () => recorder.pollTicks(dl) } : {}),
+        ...(opts.focusTicks ? { pollTicks: async () => {
+                const r = await recorder.pollTicks(dl);
+                // Detached: a quote waiting on the Jupiter bucket must never delay the next 5 s tick (the lane's own in-flight
+                // guard keeps one probe pass at a time; it never throws).
+                if (opts.exitProbes)
+                    void recorder.probeExits(probeDeps).catch(() => { });
+                return r;
+            } } : {}),
         dbBytes() {
             try {
                 const db = recorder.database;
@@ -261,6 +298,19 @@ function parseRetention(t, next, a) {
         a.focusTicks = true;
         return null;
     }
+    if (t === '--exit-probes') {
+        a.exitProbes = true;
+        a.focusTicks = true;
+        return null;
+    }
+    if (t === '--focus-module') {
+        const v = next();
+        if (!v || v.startsWith('--'))
+            return '--focus-module needs a PATH';
+        a.focusModule = resolve(v);
+        a.focusTicks = true;
+        return null;
+    }
     if (t === '--retention-mb') {
         const n = Number(next());
         if (!Number.isFinite(n) || n < 1)
@@ -278,7 +328,7 @@ function parseRetention(t, next, a) {
     return undefined;
 }
 export function parseRun(argv) {
-    const a = { intervalMs: DEFAULT_INTERVAL_MS, ticks: Infinity, maintainMs: DEFAULT_MAINTAIN_MS, maxDbBytes: DEFAULT_MAX_DB_MB * 1_000_000, noNewpairs: false, db: null, verbose: false, retentionBytes: null, retentionDays: null, focusTicks: false };
+    const a = { intervalMs: DEFAULT_INTERVAL_MS, ticks: Infinity, maintainMs: DEFAULT_MAINTAIN_MS, maxDbBytes: DEFAULT_MAX_DB_MB * 1_000_000, noNewpairs: false, db: null, verbose: false, retentionBytes: null, retentionDays: null, focusTicks: false, focusModule: null, exitProbes: false };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
         const r = parseRetention(t, () => argv[++i], a);
@@ -329,8 +379,9 @@ export function parseRun(argv) {
 export const RECORD_USAGE = `dexterm record: keep the history recorder fed with no TUI open (task-1414).
 
   dexterm record [run] [--interval S] [--ticks N | --once] [--maintain S] [--max-db-mb N] [--retention-mb N] [--retention-days D]
-                       [--focus-ticks] [--no-newpairs] [--db PATH] [--verbose]
-  dexterm record install   [--interval S] [--max-db-mb N] [--retention-mb N] [--retention-days D] [--focus-ticks] [--load] [--dry-run]
+                       [--focus-ticks] [--focus-module PATH] [--exit-probes] [--no-newpairs] [--db PATH] [--verbose]
+  dexterm record install   [--interval S] [--max-db-mb N] [--retention-mb N] [--retention-days D] [--focus-ticks]
+                           [--focus-module PATH] [--exit-probes] [--load] [--dry-run]
   dexterm record uninstall [--unload]
   dexterm record status    [--db PATH]
 
@@ -341,7 +392,10 @@ run        the collector loop: one keyless feed refresh per --interval (default
            to stay under N MB and observation never pauses. --retention-days D drops snapshot rows (sweep rows
            too) older than D days (default 90). --focus-ticks samples watchlist / held / candidate / open coins
            every 5-10 s (DexScreener batches of 30, a daily call ceiling) with 1m candles; autotrade backtests
-           read them. --no-newpairs drops the PumpPortal stream. Ctrl-C stops cleanly
+           read them. --focus-module PATH adds the coins an ESM module's focus(now) returns
+           ([{ mint, role }], role held | open | candidate | watch) to that lane. --exit-probes asks Jupiter for
+           a keyless $50 sell quote of every held focus coin once a minute (exit_probes; quotes only).
+           Both imply --focus-ticks. --no-newpairs drops the PumpPortal stream. Ctrl-C stops cleanly
            (labels whatever is due). Requests honour the data layer's rate limits, health gate and sweep budgets.
 install    write a user-level launchd LaunchAgent (no sudo) that runs \`record run\`; prints the launchctl
            command. --load also runs launchctl (off by default). --dry-run prints the plist, writes nothing.
@@ -404,7 +458,22 @@ async function run(argv, io, deps) {
         };
     })();
     const log = (s) => io.stderr.write(s);
-    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log, retentionBytes: parsed.retentionBytes, retentionDays: parsed.retentionDays, focusTicks: parsed.focusTicks });
+    // task-1786: the focus module is loaded once, up front; a module that does not load is a startup error (exit 2).
+    let extraFocus;
+    if (parsed.focusModule) {
+        try {
+            const mod = await import(__rewriteRelativeImportExtension(pathToFileURL(parsed.focusModule).href));
+            if (typeof mod.focus !== 'function')
+                throw new Error('it exports no focus(now) function');
+            const fn = mod.focus;
+            extraFocus = () => fn(Date.now());
+        }
+        catch (e) {
+            io.stderr.write(`dexterm record: --focus-module ${parsed.focusModule}: ${redactSecrets(e.message)}\n`);
+            return 2;
+        }
+    }
+    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log, retentionBytes: parsed.retentionBytes, retentionDays: parsed.retentionDays, focusTicks: parsed.focusTicks, extraFocus, exitProbes: parsed.exitProbes });
     const own = !deps.engine;
     const onSig = () => { io.stderr.write('\ndexterm record: stopping…\n'); stop.abort(); };
     if (own) {
@@ -415,7 +484,7 @@ async function run(argv, io, deps) {
     // alive between passes and node would exit mid-run (task-1504 smoke). Hold it open until the loops finish.
     const hold = own ? setInterval(() => { }, 1 << 30) : null;
     if (parsed.verbose || parsed.ticks !== Infinity)
-        io.stderr.write(`dexterm record: db ${dbPath} · interval ${Math.round(parsed.intervalMs / 1000)}s · maintain ${Math.round(parsed.maintainMs / 1000)}s · cap ${parsed.maxDbBytes === null ? 'off' : `${Math.round(parsed.maxDbBytes / 1e6)} MB`} · newpairs ${parsed.noNewpairs ? 'off' : 'on'}${parsed.retentionBytes !== null ? ` · retention ${Math.round(parsed.retentionBytes / 1e6)} MB (evict, never pause)` : ''}${parsed.retentionDays !== null ? ` · rows ${parsed.retentionDays} d` : ''} · focus ticks ${parsed.focusTicks ? 'on' : 'off'}\n`);
+        io.stderr.write(`dexterm record: db ${dbPath} · interval ${Math.round(parsed.intervalMs / 1000)}s · maintain ${Math.round(parsed.maintainMs / 1000)}s · cap ${parsed.maxDbBytes === null ? 'off' : `${Math.round(parsed.maxDbBytes / 1e6)} MB`} · newpairs ${parsed.noNewpairs ? 'off' : 'on'}${parsed.retentionBytes !== null ? ` · retention ${Math.round(parsed.retentionBytes / 1e6)} MB (evict, never pause)` : ''}${parsed.retentionDays !== null ? ` · rows ${parsed.retentionDays} d` : ''} · focus ticks ${parsed.focusTicks ? 'on' : 'off'}${parsed.focusModule ? ` · focus module ${parsed.focusModule}` : ''}${parsed.exitProbes ? ' · exit probes on' : ''}\n`);
     let result;
     let tickRes = { polls: 0, calls: 0, written: 0 };
     try {
@@ -446,7 +515,7 @@ async function run(argv, io, deps) {
 }
 function install(argv, io) {
     let intervalMs = DEFAULT_INTERVAL_MS, maxDbMb = DEFAULT_MAX_DB_MB, load = false, dry = false;
-    const ret = { retentionBytes: null, retentionDays: null, focusTicks: false };
+    const ret = { retentionBytes: null, retentionDays: null, focusTicks: false, focusModule: null, exitProbes: false };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
         const r = parseRetention(t, () => argv[++i], ret);
@@ -488,6 +557,8 @@ function install(argv, io) {
         ...(ret.retentionBytes !== null ? ['--retention-mb', String(Math.round(ret.retentionBytes / 1e6))] : []),
         ...(ret.retentionDays !== null ? ['--retention-days', String(ret.retentionDays)] : []),
         ...(ret.focusTicks ? ['--focus-ticks'] : []),
+        ...(ret.focusModule ? ['--focus-module', ret.focusModule] : []),
+        ...(ret.exitProbes ? ['--exit-probes'] : []),
     ];
     const plist = renderCollectorPlist({ label: COLLECTOR_LABEL, nodePath: process.execPath, binPath: bin, intervalMs, maxDbMb, extraArgs, logPath, workingDir: resolve(dirname(bin), '..', '..', '..') });
     if (dry) {

package/dist/packages/cli/src/rules-cmd.js

@@ -119,8 +119,9 @@ export async function rulesCommand(argv, io) {
         case 'fields': {
             io.stdout.write(`fields:  ${FIELD_NAMES.join(' ')}\n`);
             io.stdout.write(`aliases: vol volume liquidity cap mc holder organic top locked cluster% clusterpct\n`);
+            io.stdout.write(`narrative (EXPERIMENTAL, measured heat, not advice): narrative_rank narrative_score narrative:spark|ignition|peak|fading|dead|saturated (null until N → n builds the tracker)\n`);
             io.stdout.write(`signals: <field>.velocity (current ÷ mean of earlier samples in the window) · <field>.delta (current − oldest in the window)\n`);
-            io.stdout.write(`tags:    ${TAG_NAMES.map((t) => t + ':').join(' ')}  (e.g. launchpad:pump flag:mint flag:clean verified:yes sus:no; prefix ! to negate)\n`);
+            io.stdout.write(`tags:    ${TAG_NAMES.map((t) => t + ':').join(' ')}  (e.g. launchpad:pump flag:mint flag:clean verified:yes sus:no narrative:ignition narrative:saturated; prefix ! to negate)\n`);
             io.stdout.write(`values:  $1.5M 25K 2B 20% 2h 30m 3d · ops > >= < <= = != · and or not ( )\n`);
             io.stdout.write(`actions: ${ACTIONS.join(' ')}  alert(level, "text") ticket(buy|sell, size ≤ ${TICKET_SIZE_CAP}, sol|usd|pct) ask(skill) popup(${RULE_POPUP_KINDS.join('|')}) tag("label") sound(name) watch\n`);
             io.stdout.write(`limits:  cooldown (default 10m) · max n/h (default 12, cap ${MAX_PER_HOUR_CAP}) · scope ${SCOPES.join('|')}|mint:<addr> · window (default 10m)\n`);

package/dist/packages/cli/src/rules.js

@@ -1,4 +1,16 @@
+// dexterm — the rules engine's app adapter (task-1358 Tier 3). Pure helpers over @dexterm/custom's RulesEngine
+// that the key handler, the interactive loop and the Rules screen call: load `config.rules` into an engine on
+// `state.rulesUi`, feed it the screener rows every few seconds (`rulesTick`), turn its outputs into things the
+// app can show (toasts, the screen's log, PROPOSAL cards, pending UI actions the loop performs), and persist edits
+// through the config journal (so `dexterm config undo` / the journal cover rules too).
+//
+// SAFETY: a rule's outputs are alerts, annotations (watch/tag on the user's own watchlist), UI actions (popup /
+// terminal bell) and PROPOSALS. Acting on a ticket proposal opens the PAPER ticket in its editing phase (the user
+// sizes and confirms there, signer caps apply); acting on an ask proposal sends a question to the analyst. Nothing
+// in this module can arm, sign, confirm, open a live ticket or touch a mandate — there is no code path for it.
+import { classifierLiveTick } from "./classifier-live.js";
 import { devBookOf } from "./live/dev-history.js";
+import { narrativeRuleFields } from "./narratives.js";
 import { RulesEngine, ruleToJson, ruleToText, slug, applyAndJournal, describeActions, } from '../../custom/src/index.js';
 import { alertToDelivery, proposalToDelivery } from "./alerts/format.js";
 export const RULE_INPUT_MAX = 400;
@@ -56,6 +68,11 @@ export function larpGrade(verdict) {
  * `mintable > 0` fires on the real streaming values, not the on-open snapshot. A token opened by `--mint` that is
  * not in the screener feed is appended as its own row so rules still see it.
  */
+/** task-1822: the classifier's drain estimate for the `rugp` field (null when unscored or the scoring failed). */
+function rugpOf(state, mint) {
+    const p = state.classifierByMint?.get(mint)?.p;
+    return typeof p === 'number' && Number.isFinite(p) ? p : null;
+}
 export function ruleRowsOf(state) {
     const out = [];
     const seen = new Set();
@@ -70,11 +87,13 @@ export function ruleRowsOf(state) {
     // 0.1.5 dev history: the creator's recorded rugs as the `devrugs` field (local recorder only; null = unknown).
     const book = devBookOf(state);
     const devRugsOf = (mint) => book ? book.rugsFor(mint) : null;
+    // task-1818: narrative_rank / narrative_score / narrative:<state> from the ALREADY-built narratives tracker (never builds one)
+    const narr = (mint) => narrativeRuleFields(state, mint);
     for (const r of state.screener.rows) {
         if (!r.mint || r.skeleton || seen.has(r.mint))
             continue;
         seen.add(r.mint);
-        const row = Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict), devRugs: devRugsOf(r.mint) });
+        const row = Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict), devRugs: devRugsOf(r.mint), rugP: rugpOf(state, r.mint) }, narr(r.mint));
         if (r.mint === openMint)
             overlaySignalFields(row, state, r.mint);
         out.push(row);
@@ -85,9 +104,9 @@ export function ruleRowsOf(state) {
         const row = Object.assign(Object.create(null), {
             mint: v.mint, symbol: v.symbol, price: v.price, mcap: v.mcap, fdv: v.fdv, liq: v.liq, vol24: v.vol24,
             holders: v.holders, org: v.org, top10: v.top10, dev: v.dev, lpLocked: v.lpLocked,
-            cluster: clusterOf(v.mint), larp: larpGrade(state.larpByMint?.get(v.mint)?.verdict), devRugs: devRugsOf(v.mint),
+            cluster: clusterOf(v.mint), larp: larpGrade(state.larpByMint?.get(v.mint)?.verdict), devRugs: devRugsOf(v.mint), rugP: rugpOf(state, v.mint),
             ageMin: v.ageMin, chg: v.chg, launchpad: v.launchpad, flags: v.flags, verified: v.verified, sus: v.sus,
-        });
+        }, narr(v.mint));
         overlaySignalFields(row, state, v.mint);
         out.push(row);
     }
@@ -107,7 +126,7 @@ export function ruleRowsOf(state) {
             out.push(Object.assign(Object.create(null), {
                 mint: p.mint, symbol: p.symbol, mcap: p.mcap, liq: p.liq, holders: p.holders, launchpad: p.launchpad,
                 ageMin: p.createdAt ? Math.max(0, (now - p.createdAt) / 60_000) : null, bonding: p.bonding, devRugs,
-            }));
+            }, narr(p.mint)));
         }
     }
     return out;
@@ -153,6 +172,7 @@ export function rulesTick(state, now) {
     const rows = ruleRowsOf(state);
     if (!rows.length)
         return null;
+    classifierLiveTick(state, rows, now); // task-1822: fills classifierByMint for `rugp` rules (a no-op without one)
     ui.engine.observe(rows, now);
     const watch = state.live?.watch.store ?? null;
     const positions = state.live?.positions ?? null;

package/dist/packages/cli/src/screens/narrative.js

@@ -3,8 +3,13 @@
 // new launches / runners / pace / "what is working" score. No model in the hot path; the board carries
 // its own limits (name-based, X/TG-only narratives missed, honest unclassified share). w flips 1h/24h,
 // M opens the HUD popup. The board is computed in state.ts (computeNarrativeView) on entry and the tick.
+// task-1818: `n` flips to the EXPERIMENTAL heat table (@dexterm/narratives: clustered by what the name says,
+// lifecycle + traction score per narrative); ⏎ drills into one narrative's member coins, esc returns to the table.
 import { Canvas, header, footer, badge, breakpoint } from '../../../tui/src/index.js';
 import { headerModel } from "../state.js";
+import { clean } from '../../../packs/src/index.js';
+import { HEAT_NOTE } from '../../../narratives/src/index.js';
+import { heatRows, drillDetail, currentTracker, narrativesSource, UNTRUSTED_NOTE } from "../narratives.js";
 const fmtUsd = (v) => { if (v == null)
     return '—'; const a = Math.abs(v); if (a >= 1e9)
     return (v / 1e9).toFixed(2) + 'B'; if (a >= 1e6)
@@ -12,6 +17,13 @@ const fmtUsd = (v) => { if (v == null)
     return (v / 1e3).toFixed(1) + 'K'; return v.toFixed(0); };
 const fmtPct = (v) => (v == null ? '—' : (v > 0 ? '+' : '') + v.toFixed(1) + '%');
 export function renderNarrative(c, state) {
+    if (state.narrativesUi?.mode === 'heat') {
+        if (state.narrativesUi.drill)
+            renderDrill(c, state);
+        else
+            renderHeat(c, state);
+        return;
+    }
     const t = c.theme;
     const bp = breakpoint(c.w);
     header(c, headerModel(state));
@@ -27,7 +39,7 @@ export function renderNarrative(c, state) {
     if (!board || board.narratives.every((n) => n.tokens === 0)) {
         c.textC(box.x, box.y + 1, box.w, 'collecting narratives — run the app with the recorder on, or open the screener first', { fg: t.muted, bg, i: true });
         c.textC(box.x, box.y + 3, box.w, view?.error ? `(${view.error})` : 'clusters come from token names against a lexicon (owner: maintainers); X/Telegram-only narratives are missed', { fg: t.dim, bg });
-        footer(c, [['w', '1h/24h'], ['esc', 'back'], ['q', 'quit']], t.name);
+        footer(c, [['w', '1h/24h'], ['n', 'narratives (exp)'], ['esc', 'back'], ['q', 'quit']], t.name);
         return;
     }
     const shown = board.narratives.filter((n) => n.tokens > 0);
@@ -86,5 +98,145 @@ export function renderNarrative(c, state) {
     const ly = box.y + box.h - 1;
     if (wide)
         c.textC(box.x, ly, box.w, `model output: none (deterministic lexicon v${board.meta.lexicon_version}) · ${board.meta.copycat_tokens} copycat symbols · name-based · pace '*' = all tokens · compute ${board.meta.compute_ms}ms`, { fg: t.dim, bg });
-    footer(c, [['↑↓', 'move'], ['w', win === '1h' ? '→24h' : '→1h'], ['M', 'popup'], ['esc', 'back'], ['q', 'quit']], t.name);
+    footer(c, [['↑↓', 'move'], ['w', win === '1h' ? '→24h' : '→1h'], ['n', 'narratives (exp)'], ['M', 'popup'], ['esc', 'back'], ['q', 'quit']], t.name);
+}
+// ---- task-1818 EXPERIMENTAL heat table + drill-down ------------------------------------------------------------
+const heatUsd = (v) => (v == null ? '—' : '$' + fmtUsd(v));
+const fmtShare = (v) => (v == null ? '—' : (v * 100).toFixed(1) + '%');
+const fmtX = (v) => (v == null || !Number.isFinite(v) ? '—' : v.toFixed(2) + 'x');
+function lcColor(t, lc) {
+    // states are measured heat, so none is painted as a market up/down colour (no green "go")
+    return lc === 'ignition' ? t.accent : lc === 'peak' ? t.text : lc === 'fading' ? t.warn : lc === 'dead' ? t.dim : t.muted;
+}
+/** The limits line: the full HEAT_NOTE when it fits, else the short form (the note must never be the part that is cut). */
+function limitsLine(w, extra) {
+    const full = `${HEAT_NOTE} · ${UNTRUSTED_NOTE} · ${extra}`;
+    return full.length <= w ? full : `measured heat, not advice · ${UNTRUSTED_NOTE} · ${extra}`;
+}
+/** The status line under an empty heat table: building (with the one-time stall warning), failed, or nothing yet. */
+function heatPlaceholder(state) {
+    const ui = state.narrativesUi;
+    const rec = narrativesSource(state) === 'recorded';
+    if (ui?.error)
+        return [`narratives failed: ${clean(ui.error, 120)}`, 'the theme board (v) still works'];
+    if (!currentTracker(state))
+        return [rec ? 'building narratives from recorded history…' : 'building narratives from the visible rows…',
+            rec ? 'first build reads the last 26 h of the recorder: tens of seconds, the screen stays live (once per run)' : 'no recorder DB here (fixtures / replay): no history, so every narrative starts as a spark'];
+    return ['no narrative with 2+ coins yet', 'a narrative needs at least two coins whose names share a theme · measured heat, not advice'];
+}
+function renderHeat(c, state) {
+    const t = c.theme;
+    const bp = breakpoint(c.w);
+    header(c, headerModel(state));
+    const ui = state.narrativesUi;
+    const rows = heatRows(state);
+    const tr = currentTracker(state);
+    const src = narrativesSource(state) === 'recorded' ? 'recorded history' : 'visible rows';
+    const top = 2, bottom = c.h - 1;
+    const title = `NARRATIVES · EXPERIMENTAL · ${tr ? `${rows.length} narratives · ${tr.coins.size} coins` : 'building'} · ${src}${ui.busy && tr ? ' · refreshing' : ''}`;
+    const caption = bp === 'compact' ? undefined : 'measured heat, not advice';
+    const box = c.box(0, top, c.w, bottom - top, { title, caption, focus: true });
+    const bg = box.bg;
+    const keys = [['↑↓', 'move'], ['⏎', 'drill'], ['n', 'theme board'], ['esc', 'back'], ['q', 'quit']];
+    if (!rows.length) {
+        const [a, b] = heatPlaceholder(state);
+        c.textC(box.x, box.y + 1, box.w, a, { fg: t.muted, bg, i: true });
+        c.textC(box.x, box.y + 3, box.w, b, { fg: t.dim, bg });
+        c.textC(box.x, box.y + 5, box.w, HEAT_NOTE, { fg: t.dim, bg });
+        footer(c, keys, t.name);
+        return;
+    }
+    const sel = Math.max(0, Math.min(rows.length - 1, ui.selected));
+    // columns: [x, header]; a column that does not fit the box is dropped (the runner first)
+    const cols = [[1, '#', 3], [5, 'NARRATIVE', 18], [24, 'THEME', 12], [37, 'STATE', 10], [48, 'COINS', 5], [54, 'NEW/h', 5], [60, 'VOL 1h', 9], [70, 'SHARE', 6], [77, 'TRADERS', 7], [85, 'SCORE', 5], [91, 'TOP RUNNER (x · drawdown)', 28]];
+    const fits = (i) => cols[i][0] + Math.min(cols[i][2], 12) <= box.w - 1;
+    let cy = box.y;
+    cols.forEach(([x, h], i) => { if (fits(i))
+        c.text(box.x + x, cy, h, { fg: t.dim, bg }, box.w - x - 1); });
+    cy += 1;
+    c.hline(box.x, cy, box.w, { fg: t.border, bg });
+    cy += 1;
+    const scroll = Math.max(0, sel - (box.h - 6));
+    for (let i = scroll; i < rows.length; i++) {
+        if (cy >= box.y + box.h - 2)
+            break;
+        const s = rows[i];
+        const w1 = s.windows['1h'];
+        const selected = i === sel;
+        const rb = selected ? t.selBg : bg;
+        c.fill(box.x, cy, box.w, 1, ' ', { bg: rb });
+        if (selected)
+            c.put(box.x, cy, '▎', { fg: t.accent, bg: rb, soft: true });
+        const cell = (k, v, st) => { if (fits(k))
+            c.text(box.x + cols[k][0], cy, v, { ...st, bg: rb }, Math.min(cols[k][2], box.w - cols[k][0] - 1)); };
+        cell(0, s.rank == null ? '·' : String(s.rank), { fg: s.rank == null ? t.dim : t.accent, b: true });
+        cell(1, clean(s.label, 18), { fg: selected ? t.borderFocus : t.text, b: s.rank != null });
+        cell(2, s.theme ? clean(s.theme, 12) : '—', { fg: t.muted });
+        cell(3, s.lifecycle + (s.saturated ? '*' : ''), { fg: lcColor(t, s.lifecycle), b: s.lifecycle === 'ignition' });
+        cell(4, String(s.members), { fg: t.text });
+        cell(5, w1.newPerHour.toFixed(0), { fg: t.muted });
+        cell(6, heatUsd(w1.volume), { fg: t.text });
+        cell(7, fmtShare(w1.volumeShare), { fg: t.muted });
+        cell(8, String(w1.traders), { fg: t.muted });
+        cell(9, String(s.score), { fg: t.accent, b: true });
+        const r = s.topRunner;
+        cell(10, r ? `${clean(r.symbol, 10)} ${fmtX(r.x)} · ${r.drawdownPct.toFixed(0)}%` : '—', { fg: r ? t.text : t.dim });
+        cy += 1;
+    }
+    c.textC(box.x, box.y + box.h - 1, box.w, limitsLine(box.w, '* = copy-cat saturated'), { fg: t.dim, bg });
+    footer(c, keys, t.name);
+}
+function renderDrill(c, state) {
+    const t = c.theme;
+    header(c, headerModel(state));
+    const ui = state.narrativesUi;
+    const d = drillDetail(state);
+    const top = 2, bottom = c.h - 1;
+    const keys = [['↑↓', 'move'], ['⏎', 'open coin'], ['esc', 'table'], ['q', 'quit']];
+    if (!d) {
+        const box = c.box(0, top, c.w, bottom - top, { title: 'NARRATIVE · EXPERIMENTAL', focus: true });
+        c.textC(box.x, box.y + 1, box.w, 'this narrative is no longer tracked (esc returns to the table)', { fg: t.muted, bg: box.bg, i: true });
+        footer(c, keys, t.name);
+        return;
+    }
+    const w1 = d.windows['1h'];
+    const title = `NARRATIVE · ${clean(d.label, 24)} · ${d.lifecycle}${d.saturated ? ' · copy-cat saturated' : ''} · ${d.memberList.length} coin${d.memberList.length === 1 ? '' : 's'} · EXPERIMENTAL`;
+    const box = c.box(0, top, c.w, bottom - top, { title, caption: 'measured heat, not advice · members in spawn order', focus: true });
+    const bg = box.bg;
+    let cy = box.y;
+    c.text(box.x + 1, cy, `lifecycle rule (${d.lifecycle}): ${d.lifecycleRule}`, { fg: lcColor(t, d.lifecycle), bg }, box.w - 2);
+    cy += 1;
+    c.text(box.x + 1, cy, `1h: vol ${heatUsd(w1.volume)} · share ${fmtShare(w1.volumeShare)} · new/h ${w1.newPerHour.toFixed(0)} · traders ${w1.traders} · score ${d.score}${d.rank ? ` · rank ${d.rank}` : ''}${d.theme ? ` · theme ${clean(d.theme, 16)}` : ''}`, { fg: t.muted, bg }, box.w - 2);
+    cy += 1;
+    const cols = [[1, '#', 4], [6, 'SYMBOL', 12], [19, 'NAME', 26], [46, 'X SINCE 1ST', 11], [58, 'LIQ', 9], [68, 'VOL 1h', 9]];
+    const fits = (i) => cols[i][0] + Math.min(cols[i][2], 8) <= box.w - 1;
+    cols.forEach(([x, h], i) => { if (fits(i))
+        c.text(box.x + x, cy, h, { fg: t.dim, bg }); });
+    cy += 1;
+    c.hline(box.x, cy, box.w, { fg: t.border, bg });
+    cy += 1;
+    const n = d.memberList.length;
+    const sel = Math.max(0, Math.min(n - 1, ui.drill.selected));
+    const scroll = Math.max(0, sel - (box.h - 8));
+    for (let i = scroll; i < n; i++) {
+        if (cy >= box.y + box.h - 1)
+            break;
+        const m = d.memberList[i];
+        const selected = i === sel;
+        const rb = selected ? t.selBg : bg;
+        c.fill(box.x, cy, box.w, 1, ' ', { bg: rb });
+        if (selected)
+            c.put(box.x, cy, '▎', { fg: t.accent, bg: rb, soft: true });
+        const cell = (k, v, fg) => { if (fits(k))
+            c.text(box.x + cols[k][0], cy, v, { fg, bg: rb }, Math.min(cols[k][2], box.w - cols[k][0] - 1)); };
+        cell(0, `#${m.spawn}`, t.dim);
+        cell(1, clean(m.symbol, 12), selected ? t.borderFocus : t.text);
+        cell(2, clean(m.name, 26), t.muted);
+        cell(3, fmtX(m.x), m.x == null ? t.dim : m.x >= 1 ? t.up : t.down);
+        cell(4, heatUsd(m.liq), t.text);
+        cell(5, heatUsd(m.vol1h), t.text);
+        cy += 1;
+    }
+    c.textC(box.x, box.y + box.h - 1, box.w, limitsLine(box.w, 'x = now vs first $10K+ pool price'), { fg: t.dim, bg });
+    footer(c, keys, t.name);
 }

package/dist/packages/cli/src/skill-eval-build.js

@@ -11,7 +11,7 @@
 // symbol is written (the name and symbol are read only to compute the domain-match boolean).
 import { linkFeatures } from '../../data/src/index.js';
 import { LABELER_VERSION } from '../../recorder/src/index.js';
-import { SKILL_EVAL_SCHEMA } from '../../packs/src/index.js';
+import { SKILL_EVAL_SCHEMA, cutoffIso } from '../../packs/src/index.js';
 function readCache(db, ns, mint) {
     const row = db.prepare('SELECT json, fetched_at FROM cache WHERE ns = ? AND key = ?').get(ns, mint);
     if (!row)
@@ -47,6 +47,11 @@ export function buildSkillEvalSet(db, opts = {}) {
         let picked = null;
         for (const o of outs) {
             const t0 = Number(o.t0);
+            // A t0 that is not a valid time can never anchor point-in-time evidence (and would poison the split). task-1982
+            if (Number.isNaN(new Date(t0).getTime())) {
+                excluded.bad_t0 = (excluded.bad_t0 ?? 0) + 1;
+                continue;
+            }
             const srcs = [['jupiter', jup], ['dexscreener', ds]]
                 .filter((x) => !!x[1] && x[1].fetched_at >= t0 && x[1].fetched_at <= t0 + lagMs);
             if (srcs.length) {
@@ -101,7 +106,7 @@ export function buildSkillEvalSet(db, opts = {}) {
         horizon_sec: horizon,
         label_rule: `recorder outcome at ${horizon}s (keyless proxy, labeler ${LABELER_VERSION}); bad = rug ∪ dead, ok = flat ∪ fade ∪ runner; unobserved dropped`,
         evidence_rule: `link features from the cached DexScreener/Jupiter token record only when it was fetched within ${lagMs / 1000}s after the row's t0 (latest such t0 per coin); rug-check features from that t0 snapshot`,
-        split_rule: `by time: the latest ${Math.round(testFrac * 100)}% of rows by t0 (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST split, fixed before tuning`,
+        split_rule: `by time: the latest ${Math.round(testFrac * 100)}% of rows by t0 (t0 ≥ ${cutoffIso(cutoff)}) are the held-out TEST split, fixed before tuning`,
         cutoff_t0: cutoff,
         counts: { rows: rows.length, train: train.length, test: test.length, bad_train: train.filter((r) => r.bad).length, bad_test: test.filter((r) => r.bad).length, excluded },
         rows,

package/dist/packages/cli/src/state.js

@@ -301,6 +301,7 @@ export function makeFixtureState(opts = {}) {
         ai: null,
         analystByMint: new Map(),
         larpByMint: new Map(),
+        classifierByMint: new Map(),
         colorDepth: opts.colorDepth ?? 'truecolor',
     };
     if (opts.priceMode)

package/dist/packages/cli/src/version.js

@@ -1,3 +1,3 @@
 // The one place the app's version lives (task-1397). --version, the help banner and `dexterm update` read it;
 // cli.test.ts keeps it equal to packages/cli/package.json (release.yml refuses a tag that differs).
-export const VERSION = '0.2.0';
+export const VERSION = '0.2.2';

package/dist/packages/custom/src/rules.js

@@ -3,7 +3,8 @@ export const FIELDS = {
     vol5m: (r) => r.vol5m, vol1h: (r) => r.vol1h, vol24: (r) => r.vol24,
     holders: (r) => r.holders, org: (r) => r.org, top10: (r) => r.top10, dev: (r) => r.dev,
     lplocked: (r) => r.lpLocked, bundled: (r) => r.bundled, snipers: (r) => r.snipers,
-    cluster: (r) => r.cluster, larp: (r) => r.larp, devrugs: (r) => r.devRugs,
+    cluster: (r) => r.cluster, larp: (r) => r.larp, devrugs: (r) => r.devRugs, rugp: (r) => r.rugP,
+    narrative_rank: (r) => r.narrativeRank, narrative_score: (r) => r.narrativeScore,
     fresh: (r) => r.fresh, mintable: (r) => r.mintable, freezable: (r) => r.freezable,
     age: (r) => r.ageMin, m5: (r) => r.chg?.m5, h1: (r) => r.chg?.h1, h6: (r) => r.chg?.h6, h24: (r) => r.chg?.h24,
     buys: (r) => r.buys, sells: (r) => r.sells, bonding: (r) => r.bonding,
@@ -16,6 +17,9 @@ const TAGS = {
     flag: (r, v) => (v === 'clean' ? (r.flags ?? []).length === 0 : (r.flags ?? []).map((f) => f.toLowerCase()).includes(v.toLowerCase())),
     verified: (r, v) => (v === 'yes') === !!r.verified,
     sus: (r, v) => (v === 'yes') === !!r.sus,
+    // task-1818: `narrative:ignition` (or spark / peak / fading / dead) = the coin's narrative is in that lifecycle state;
+    // `narrative:saturated` = copy-cat saturated. An untracked coin matches nothing (so `!narrative:dead` is true for it).
+    narrative: (r, v) => { const k = v.toLowerCase(); return k === 'saturated' ? r.narrativeSaturated === true : !!r.narrativeLifecycle && r.narrativeLifecycle === k; },
 };
 export const TAG_NAMES = Object.keys(TAGS);
 export const ACTIONS = ['alert', 'ticket', 'ask', 'popup', 'tag', 'sound', 'watch'];

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

@@ -35,6 +35,6 @@ sources:
 date: 2026-10-16
 ---
 
-Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/
+Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. Read-only from chat: `/check <CA>` (one coin's LARP score and risk facts: authorities, top-10 holders, dev share, LP lock, liquidity, each with the age of its data), `/top [N]` (the screener's trending list, 1 to 10, the runner's own coins marked) and `/signals [N]` (the last 1 to 20 signals the runner raised: screen matches, safety refusals, the drain guard, stuck bags, halts, fills); data, not advice, and they cannot reach any write. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/
 
 CLI: `dexterm telegram`.

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

@@ -0,0 +1,41 @@
+---
+id: classification-models
+title: Pick a classification model (Kev, hosted Jev, or the built-in scores)
+kind: app-help
+screen: all
+feature: classifier
+tags:
+  - app-help
+  - classifier
+  - classification
+  - kev
+  - jev
+  - model
+  - probability
+  - rug
+  - drain
+  - llama
+  - calibrated
+  - typesafe
+  - experimental
+commands:
+  - classifier
+tools:
+  - classify_coin
+  - classify_batch
+  - classifier_status
+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
+---
+
+EXPERIMENTAL. A classification model answers typed questions about one coin with a probability per answer: p(drain within 6 h) and RUG / WIN / DUD over 6 h, or a narrative category. `dexterm classifier list` shows the choices: `heuristic` (the built-in H1 rug score and LARP link score; the default, no download), `kev-local` (an open Kev decision model on your own machine through llama.cpp: `dexterm classifier pull kev-4b-q4` shows the size and source and asks first, verifies the sha256, then `dexterm classifier pick kev-local kev-4b-q4` and `dexterm classifier serve`), `jev-hosted` (TypeSafe's hosted Jev with your own API key: `dexterm classifier key set`; per-call cost and a daily call cap), `jev-open` (the open JEV students on a vLLM server), and `claude` / `ollama-llm` zero-shot baselines. `dexterm classifier doctor` reads RAM, CPU and GPU/VRAM and recommends a tier. If the picked model is unreachable the built-in scores answer and say so. Agents use the `classify_coin`, `classify_batch` (triage: flag / pass / escalate) and `classifier_status` MCP tools; a watch rule can use `rugp` (e.g. `when rugp > 0.8 then alert(warn, "...")`). How each model scored on dexterm's own labelled history is on the docs page. Every answer is a model estimate with the model id, never advice. Docs: https://dexterm.xyz/docs/classifier/
+
+CLI: `dexterm classifier`.

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

@@ -0,0 +1,45 @@
+---
+id: narratives-tracker
+title: Track memes and narratives (dexterm narratives, experimental)
+kind: app-help
+screen: narrative
+feature: narratives
+tags:
+  - app-help
+  - narratives
+  - narrative
+  - memes
+  - meme
+  - copycat
+  - lifecycle
+  - ignition
+  - heat
+  - saturated
+  - experimental
+keys:
+  - n
+  - enter
+actions:
+  - narrative.view
+  - narrative.drill
+commands:
+  - narratives
+tools:
+  - narratives_top
+  - narrative_detail
+  - narrative_of
+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
+---
+
+EXPERIMENTAL. The narratives tracker groups coins by the theme their name and ticker carry (ticker puns, animals, celebrities, AI agents, seasonal events, copy-cats of a runner) and measures each theme per window: coins, new-coin rate, volume share, unique-trader growth, top runner and drawdown, a lifecycle state (spark / ignition / peak / fading / dead, with the rule that set it) and a copy-cat saturation flag. On the N screen, n flips the board into the NARRATIVES table (the first switch reads the last 26 h of recorded history and takes tens of seconds), enter to see a narrative's coins in spawn order, esc to go back. `dexterm narratives [top|detail ID|of MINT|export]` prints the same from the recorder; the analyst uses narratives_top, narrative_detail and narrative_of. Rules can use narrative_rank, narrative_score and the tags narrative:ignition / narrative:saturated. Keyless and local; measured heat, not advice.
+
+Keys: `n` (narrative), `⏎` (narrative). CLI: `dexterm narratives`.