dexterm-cli 0.2.0 → 0.2.1

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/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.1';

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/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`.

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

@@ -0,0 +1,38 @@
+---
+id: strategy-dashboard
+title: Track how your autotrade strategies perform in a browser, on this machine only (dexterm dash)
+kind: app-help
+screen: all
+tags:
+  - app-help
+  - dash
+  - dashboard
+  - performance
+  - strategies
+  - track
+  - equity
+  - drawdown
+  - compare
+  - baseline
+  - rugs
+  - stuck
+  - browser
+  - web
+  - phone
+commands:
+  - dash
+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 dash` reads your own autotrade run ledgers ($DEXTERM_HOME/autotrade/runs) and serves a dashboard on http://127.0.0.1:4317/ (loopback only; no account, no cloud, nothing leaves the machine; read-only). Views: Overview (every strategy side by side with an equity sparkline), Strategy (equity curve, drawdown, exit reasons, open positions with the engine mark and the realizable value from the last cached pool read, every trade), Rugs & stuck (closed at -80% or worse and stuck positions written off at what they actually sold), Compare (each strategy minus a --baseline with the 95% interval of the difference) and Live status; it refreshes every 30 s. Every number carries its sample size; under 20 closed trades a strategy is exploratory. Flags: --port, --home (repeat for several homes), --baseline ID, --books FILE (your own script's books), --allow-host NAME (a private proxy in front), --json, --export DIR [--redact-mints] (a static read-only snapshot). PAPER results are simulated. Not financial advice.
+
+CLI: `dexterm dash`.