dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/cli/src/dash/data.js

@@ -0,0 +1,217 @@
+// `dexterm dash` (task-1749): the DATA behind the strategy performance dashboard. Read-only, local, no network:
+//   - every autotrade home given (a DEXTERM_HOME): its run ledgers (autotrade/runs/*.jsonl) through the strategy-stats
+//     definitions (@dexterm/autotrade strategy-stats.ts: the challenge control's math), its service heartbeat and the
+//     fleet status (open positions with the engine's mark, spend, halts)
+//   - the market cache DB (read-only) for the last pool liquidity of an open coin, so an open position shows its
+//     REALIZABLE value next to the engine mark, with the age of that pool read; nothing is fetched
+//   - optional "books" files (dexterm-dash-books/1): other books (e.g. a SOL challenge run by hand or by an agent),
+//     labels, groups, a baseline and status cards, produced by the user's own scripts; their trades go through the
+//     same definitions
+// The output never carries an absolute path, a key, a wallet address or a token: homes are named by their label.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { readStrategyLedgers, strategyRow, equityCurve, compareToBase, decisionRule, realizableUsd, MIN_CLOSED, RUG_PCT, STUCK_WRITE_OFF_MIN, } from '../../../autotrade/src/strategy-stats.js';
+export const PAPER_LABEL = 'Paper trading, not financial advice.';
+export const DASH_SCHEMA = 'dexterm-dash/1';
+export const BOOKS_SCHEMA = 'dexterm-dash-books/1';
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const fin = (x) => typeof x === 'number' && Number.isFinite(x);
+const r2 = (x) => Math.round(x * 100) / 100;
+const r1 = (x) => Math.round(x * 10) / 10;
+const alive = (pid) => { if (!fin(pid))
+    return false; try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** A home's label: the folder that holds `.dexterm` (e.g. c100-control), else the folder's own name. */
+export function homeLabel(dir) { const b = basename(dir); return b === '.dexterm' ? basename(dirname(dir)) || b : b; }
+/** The last cached pool read of each mint (ns ds:token) from the market cache DB, read-only. Missing DB: empty. */
+export function cachedPools(dbPath, mints) {
+    const out = new Map();
+    if (!dbPath || !mints.length || !existsSync(dbPath))
+        return out;
+    let db = null;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+        const q = db.prepare('SELECT json, fetched_at FROM cache WHERE ns = ? AND key = ?');
+        for (const m of new Set(mints)) {
+            const r = q.get('ds:token', m);
+            if (!r)
+                continue;
+            try {
+                const p = JSON.parse(r.json)?.pair;
+                if (fin(p?.liquidityUsd))
+                    out.set(m, { liqUsd: p.liquidityUsd, at: fin(p.fetchedAt) ? p.fetchedAt : r.fetched_at });
+            }
+            catch { /* torn row */ }
+        }
+    }
+    catch { /* locked or not a dexterm cache: no pool reads */ }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* closed */ }
+    }
+    return out;
+}
+/** The service heartbeat + fleet status of one home as a status card (no paths, no pids beyond alive/dead). */
+export function homeStatus(h, now) {
+    const at = join(h.dir, 'autotrade');
+    const hb = readJson(join(at, 'service', 'heartbeat.json'));
+    const fl = readJson(join(at, 'fleet-status.json'));
+    const items = [];
+    let state = 'idle';
+    if (hb) {
+        const age = fin(hb.heartbeatAt) ? Math.round((now - hb.heartbeatAt) / 1000) : null;
+        const up = hb.state === 'running' && alive(hb.pid) && age !== null && age < 120;
+        state = up ? 'ok' : hb.state === 'running' ? 'down' : 'idle';
+        items.push(['Service', up ? 'running' : hb.state === 'running' ? 'NOT running (stale heartbeat)' : String(hb.state ?? 'unknown')]);
+        if (age !== null)
+            items.push(['Heartbeat', `${age < 120 ? `${age} s` : `${Math.round(age / 60)} min`} ago`]);
+        if (fin(hb.dataAgeMs))
+            items.push(['Market data age', `${Math.round(hb.dataAgeMs / 1000)} s`]);
+    }
+    else
+        items.push(['Service', 'no service heartbeat (not installed or never run)']);
+    if (fl) {
+        const ms = fl.members ?? [];
+        if (fin(fl.startedAt))
+            items.push(['Fleet started', new Date(fl.startedAt).toISOString()]);
+        if (fl.haltReason) {
+            items.push(['Fleet halt', String(fl.haltReason)]);
+            if (state === 'ok')
+                state = 'warn';
+        }
+        const running = ms.filter((m) => m.state === 'running').length;
+        items.push(['Strategies running', `${running} of ${ms.length}`]);
+        const halted = ms.filter((m) => m.haltReason).map((m) => `${m.id}: ${m.haltReason}`);
+        if (halted.length) {
+            items.push(['Halted', halted.join('; ')]);
+            if (state === 'ok')
+                state = 'warn';
+        }
+        const spend = ms.reduce((s, m) => s + (fin(m.spend?.todayUsd) ? m.spend.todayUsd : 0), 0);
+        items.push(['Model spend today', `$${spend.toFixed(2)}`]);
+    }
+    return { title: `Autotrade · ${h.label}`, state, items, updatedAt: fin(hb?.heartbeatAt) ? hb.heartbeatAt : null };
+}
+function openFromFleet(h, now) {
+    const fl = readJson(join(h.dir, 'autotrade', 'fleet-status.json'));
+    const out = new Map();
+    if (!fl?.members)
+        return out;
+    const mints = fl.members.flatMap((m) => (m.open ?? []).map((o) => o.mint)).filter(Boolean);
+    const pools = cachedPools(h.db, mints);
+    for (const m of fl.members) {
+        out.set(m.id, (m.open ?? []).map((o) => {
+            const cost = fin(o.costUsd) ? o.costUsd : null;
+            const mark = cost !== null ? cost + (fin(o.pnlUsd) ? o.pnlUsd : 0) : null;
+            const pool = o.mint ? pools.get(o.mint) : undefined;
+            // a stuck position has no pool to sell into: realizable 0 whatever the last read said
+            const rv = o.stuck ? 0 : mark !== null ? realizableUsd(mark, pool?.liqUsd) : null;
+            return { symbol: o.symbol ?? null, mint: o.mint ?? null, profile: o.profile ?? null, costUsd: cost, markUsd: mark === null ? null : r2(mark), markPct: fin(o.pnlPct) ? o.pnlPct : null, stuck: !!o.stuck,
+                liqUsd: pool ? Math.round(pool.liqUsd) : null, liqAt: pool?.at ?? null, realizableUsd: rv === null ? null : r2(rv), realizablePct: rv === null || !cost ? null : r1((rv / cost - 1) * 100), openedAt: null };
+        }));
+    }
+    return out;
+}
+const rugsOf = (closed) => closed.filter((c) => c.writtenOff || (fin(c.pnlPct) && c.pnlPct <= RUG_PCT) || (c.stuck && !c.writtenOff));
+function fromLedger(id, m, h, fleetOpen, now) {
+    const row = strategyRow(id, m, { now });
+    // the engine's book is the live truth for what is open; the ledger fold is the fallback when no fleet status exists
+    // a stuck bag the engine still holds but the ledger fold already wrote off is CLOSED here (at its realizable value),
+    // so it is not listed open a second time
+    const heldOff = new Set(m.writtenOff.filter((w) => w.held).map((w) => w.mint));
+    const open = fleetOpen ? fleetOpen.filter((o) => !(o.stuck && heldOff.has(o.mint))) : m.openPositions.map((p) => ({ symbol: p.symbol, mint: p.mint, profile: p.profile, costUsd: p.costUsd, markUsd: null, markPct: null, stuck: p.stuckSince !== null, liqUsd: null, liqAt: null, realizableUsd: p.stuckSince !== null ? r2(p.realizedUsd) : null, realizablePct: null, openedAt: p.openedAt }));
+    return { id, label: m.basedOn?.version ? `v${m.basedOn.version}` : '', group: h.label, source: 'autotrade', home: h.label, unit: 'USD', mode: m.mode, version: m.basedOn?.version ?? null, baseline: false,
+        row, equity: equityCurve(m.closed, m.startUsd), trades: m.closed, open, rugs: rugsOf(m.closed), lastEventAt: m.lastT, firstEventAt: m.firstT };
+}
+function fromBook(b, now) {
+    const closed = (b.trades ?? []).filter((t) => fin(t.t) && fin(t.pnlPct)).map((t) => ({ t: t.t, openedAt: t.openedAt ?? null, mint: t.mint ?? null, symbol: t.symbol ?? null, pnlPct: t.pnlPct, pnlUsd: fin(t.pnl) ? t.pnl : fin(t.pnlUsd) ? t.pnlUsd : null,
+        costUsd: fin(t.cost) ? t.cost : null, exitReason: t.exitReason ?? null, stuck: !!t.writtenOff, writtenOff: !!t.writtenOff, reason: t.reason, profile: t.profile ?? null, entryAgeMin: fin(t.entryAgeMin) ? t.entryAgeMin : null }))
+        .sort((a, b2) => a.t - b2.t);
+    const ts = closed.map((c) => c.openedAt ?? c.t);
+    const firstT = fin(b.firstT) ? b.firstT : ts.length ? Math.min(...ts) : null;
+    const open = (b.open ?? []).map((o) => ({ symbol: o.symbol ?? null, mint: o.mint ?? null, profile: o.profile ?? null, costUsd: fin(o.cost) ? o.cost : null, markUsd: fin(o.mark) ? o.mark : null, markPct: fin(o.markPct) ? o.markPct : null, stuck: !!o.stuck,
+        liqUsd: null, liqAt: null, realizableUsd: fin(o.realizable) ? o.realizable : null, realizablePct: fin(o.realizable) && fin(o.cost) && o.cost ? r1((o.realizable / o.cost - 1) * 100) : null, openedAt: o.openedAt ?? null }));
+    const m = { entries: fin(b.entries) ? b.entries : closed.length + open.length, closed, open: open.length, writtenOff: closed.filter((c) => c.writtenOff), stuckOpen: [], abandoned: [], adopted: 0, firstT };
+    return { id: b.id, label: b.label ?? '', group: b.group ?? 'books', source: 'book', home: b.group ?? 'books', unit: b.unit ?? 'USD', mode: b.mode ?? 'paper', version: b.version ?? null, baseline: false,
+        row: strategyRow(b.id, m, { now }), equity: equityCurve(closed, fin(b.start) ? b.start : null), trades: closed, open, rugs: rugsOf(closed),
+        lastEventAt: closed.length ? closed[closed.length - 1].t : firstT, firstEventAt: firstT };
+}
+export function readBooksFile(p) {
+    const j = readJson(p);
+    return j && j.schema === BOOKS_SCHEMA ? j : null;
+}
+/** Everything the dashboard shows, from the homes and books files given. */
+export function collectDash({ homes, books = [], baseline = null, now = Date.now() }) {
+    const strategies = [];
+    const status = [];
+    const notes = [];
+    const labels = {};
+    const groups = {};
+    let order = [];
+    let base = baseline;
+    for (const h of homes) {
+        const runs = join(h.dir, 'autotrade', 'runs');
+        if (!existsSync(runs)) {
+            notes.push(`${h.label}: no autotrade run ledgers yet`);
+            continue;
+        }
+        const M = readStrategyLedgers(runs, { now });
+        const fo = openFromFleet(h, now);
+        for (const [id, m] of Object.entries(M))
+            strategies.push(fromLedger(id, m, h, fo.get(id), now));
+        status.push(homeStatus(h, now));
+    }
+    for (const f of books) {
+        const b = readBooksFile(f);
+        if (!b) {
+            notes.push(`books file ${basename(f)}: missing or not ${BOOKS_SCHEMA}`);
+            continue;
+        }
+        for (const x of b.books ?? [])
+            strategies.push(fromBook(x, now));
+        Object.assign(labels, b.labels ?? {});
+        Object.assign(groups, b.groups ?? {});
+        if (b.order)
+            order = [...order, ...b.order];
+        base ??= b.baseline ?? null;
+        status.unshift(...(b.status ?? [])); // the books' own cards first (what the user runs by hand)
+        notes.push(...(b.notes ?? []));
+    }
+    for (const s of strategies) {
+        if (labels[s.id])
+            s.label = labels[s.id];
+        if (groups[s.id])
+            s.group = groups[s.id];
+        s.baseline = s.id === base;
+    }
+    const rank = (id) => { const i = order.indexOf(id); return i < 0 ? 1e6 : i; };
+    strategies.sort((a, b) => Number(b.baseline) - Number(a.baseline) || rank(a.id) - rank(b.id) || a.group.localeCompare(b.group) || a.id.localeCompare(b.id));
+    const baseS = strategies.find((s) => s.baseline) ?? null;
+    const pcts = (s) => s.trades.map((c) => c.pnlPct).filter(fin);
+    const comparisons = baseS ? strategies.filter((s) => s !== baseS).map((s) => compareToBase(s.id, pcts(s), baseS.id, pcts(baseS))) : [];
+    return {
+        schema: DASH_SCHEMA, generatedAt: now, paper: PAPER_LABEL,
+        definitions: { minClosed: MIN_CLOSED, rugPct: RUG_PCT, writeOffMin: STUCK_WRITE_OFF_MIN, text: [
+                `Closed = trades the engine closed plus stuck positions written off: no sell for >= ${STUCK_WRITE_OFF_MIN} min (or dropped stuck at a run end) closes at what was actually sold; the unsold rest counts 0.`,
+                `Mean % on cost = the average return per closed trade, with a 95% bootstrap interval (4000 resamples). Wide interval = the data cannot tell yet.`,
+                `Rug = a closed trade at ${RUG_PCT}% or worse on cost. Rug rate interval: Wilson 95%.`,
+                `Under ${MIN_CLOSED} closed trades a strategy is EXPLORATORY: read nothing into it. ETA to ${MIN_CLOSED} = the closed trades still needed / entries per day so far.`,
+                `Realizable = the engine's mark sold into the last pool read from the local cache (impact on half the liquidity, 2.3% fees and slippage); a stuck position is 0.`,
+                `Equity = the starting book plus realized P/L in close order; drawdown is from the running peak.`,
+            ] },
+        baseline: baseS?.id ?? null, decisionRule: baseS ? decisionRule(baseS.id) : null, strategies, comparisons, status, notes,
+    };
+}

package/dist/packages/cli/src/dash/server.js

@@ -0,0 +1,92 @@
+// `dexterm dash` (task-1749): the loopback server and the static export of the strategy performance dashboard.
+// Binds 127.0.0.1 only. GET/HEAD only. Serves four files from assets/dash plus /api/dash.json (recomputed at most every
+// few seconds). A Host header outside the allow list is refused (DNS-rebinding guard: a web page cannot read the
+// dashboard through a hostname that resolves to 127.0.0.1); a private proxy in front (e.g. `tailscale serve`) is
+// allowed by naming its host with --allow-host. No external request is made or referenced: the page has no CDN, font
+// or analytics URL, and the CSP forbids any.
+import { createServer } from 'node:http';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectDash } from "./data.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const ASSET_DIR = resolve(HERE, '..', '..', 'assets', 'dash');
+export const ASSETS = { '/': 'index.html', '/index.html': 'index.html', '/dash.css': 'dash.css', '/dash.js': 'dash.js', '/icon.svg': 'icon.svg' };
+const TYPES = { html: 'text/html; charset=utf-8', css: 'text/css; charset=utf-8', js: 'text/javascript; charset=utf-8', svg: 'image/svg+xml', json: 'application/json; charset=utf-8' };
+export const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+/** Is this Host header one we serve? Loopback names on any port, plus the hosts allowed explicitly (with or without a port). */
+export function hostAllowed(host, allow) {
+    if (!host)
+        return false;
+    const h = host.toLowerCase();
+    const name = h.startsWith('[') ? h.slice(0, h.indexOf(']') + 1) : h.replace(/:\d+$/, '');
+    if (name === '127.0.0.1' || name === 'localhost' || name === '[::1]')
+        return true;
+    return allow.some((a) => { const x = a.toLowerCase(); return x === h || x === name; });
+}
+export function startDashServer(opts, port) {
+    let cache = null;
+    const data = () => {
+        const now = Date.now();
+        if (!cache || now - cache.at > (opts.cacheMs ?? 5000))
+            cache = { at: now, body: JSON.stringify(collectDash({ homes: opts.homes, books: opts.books, baseline: opts.baseline, now })) };
+        return cache.body;
+    };
+    const server = createServer((req, res) => {
+        const base = { 'Content-Security-Policy': CSP, 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer', 'Cache-Control': 'no-store' };
+        if (!hostAllowed(req.headers.host, opts.allowHosts)) {
+            res.writeHead(421, { ...base, 'Content-Type': 'text/plain' });
+            res.end('misdirected request: this host name is not allowed (dexterm dash --allow-host NAME)\n');
+            return;
+        }
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405, { ...base, Allow: 'GET, HEAD' });
+            res.end();
+            return;
+        }
+        const path = (req.url ?? '/').split('?')[0];
+        try {
+            if (path === '/api/dash.json') {
+                const body = data();
+                res.writeHead(200, { ...base, 'Content-Type': TYPES.json });
+                res.end(req.method === 'HEAD' ? undefined : body);
+                return;
+            }
+            const file = ASSETS[path];
+            if (!file) {
+                res.writeHead(404, { ...base, 'Content-Type': 'text/plain' });
+                res.end('not found\n');
+                return;
+            }
+            const body = readFileSync(join(ASSET_DIR, file));
+            res.writeHead(200, { ...base, 'Content-Type': TYPES[file.split('.').pop()] ?? 'application/octet-stream' });
+            res.end(req.method === 'HEAD' ? undefined : body);
+        }
+        catch (e) {
+            res.writeHead(500, { ...base, 'Content-Type': 'text/plain' });
+            res.end(`dashboard error: ${String(e?.message ?? e).slice(0, 200)}\n`);
+        }
+    });
+    return new Promise((ok, fail) => { server.once('error', fail); server.listen(port, '127.0.0.1', () => { server.off('error', fail); ok(server); }); });
+}
+/**
+ * A static, read-only SNAPSHOT: the same page + the data as data.json (the page reads it instead of /api/dash.json and
+ * shows "snapshot" with its time, no auto-refresh). `redactMints` drops the mints (coin symbols stay).
+ */
+export function exportSnapshot(d, outDir, { redactMints = false } = {}) {
+    mkdirSync(outDir, { recursive: true });
+    const data = redactMints ? JSON.parse(JSON.stringify(d, (k, v) => (k === 'mint' ? null : v))) : d;
+    const written = [];
+    for (const f of new Set(Object.values(ASSETS))) {
+        let body = readFileSync(join(ASSET_DIR, f), 'utf8');
+        if (f === 'index.html')
+            body = body.replace('content="api/dash.json"', 'content="data.json"').replace('data-mode="live"', 'data-mode="snapshot"');
+        writeFileSync(join(outDir, f), body);
+        written.push(f);
+    }
+    writeFileSync(join(outDir, 'data.json'), JSON.stringify({ ...data, snapshot: true }));
+    written.push('data.json');
+    writeFileSync(join(outDir, '_headers'), `/*\n  Content-Security-Policy: ${CSP}\n  X-Content-Type-Options: nosniff\n  Referrer-Policy: no-referrer\n`);
+    written.push('_headers');
+    return written;
+}

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

@@ -0,0 +1,113 @@
+// `dexterm dash` (task-1749): the STRATEGY PERFORMANCE DASHBOARD. Local-first: it reads your own autotrade run ledgers
+// ($DEXTERM_HOME/autotrade/runs) and serves a page on 127.0.0.1 only; no account, no cloud, nothing leaves the machine.
+// Read-only: it never writes into the engine's state. PAPER results are simulated; not financial advice.
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { dextermHome } from '../../custom/src/index.js';
+import { defaultDbPath } from '../../data/src/index.js';
+import { collectDash, homeLabel } from "./dash/data.js";
+import { exportSnapshot, startDashServer } from "./dash/server.js";
+export const DASH_PORT = 4317;
+export const DASH_HELP = `dexterm dash: track how your autotrade strategies perform, in a browser, on this machine only. Read-only.
+
+  dexterm dash                          serve the dashboard on http://127.0.0.1:${DASH_PORT}/ (Ctrl-C stops it)
+  dexterm dash --json                   print the numbers the page shows and exit
+  dexterm dash --export DIR [--redact-mints]   write a static read-only snapshot (the page + data.json) and exit
+
+  --port N            the loopback port (default ${DASH_PORT}; 0 = any free port)
+  --home DIR          a dexterm home to read (default $DEXTERM_HOME or ~/.dexterm); repeat for several
+  --db PATH           the market cache DB for pool reads (default: dexterm.db next to a .dexterm home, else DEXTERM_DB_PATH or the default DB)
+  --books FILE        add books from a dexterm-dash-books/1 JSON file (your own script's output); repeat for several
+  --baseline ID       the strategy every other one is compared against
+  --allow-host NAME   also answer requests for this host name (a private proxy in front, e.g. tailscale serve)
+
+  Overview, strategy detail, rugs & stuck, compare (vs the baseline, with the 95% interval) and live status, refreshed
+  every 30 s. The server binds 127.0.0.1 only, makes no network request and loads nothing from the internet.
+  PAPER results are simulated. Not financial advice.`;
+const VALUE = new Set(['port', 'home', 'db', 'books', 'baseline', 'allow-host', 'export']);
+const BOOL = new Set(['json', 'help', 'redact-mints']);
+function parse(argv) {
+    const o = { _: [], flags: new Map(), bools: new Set() };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-h') {
+            o.bools.add('help');
+            continue;
+        }
+        if (!a.startsWith('--')) {
+            o._.push(a);
+            continue;
+        }
+        const [k, inline] = a.slice(2).split(/=(.*)/s, 2);
+        if (BOOL.has(k)) {
+            o.bools.add(k);
+            continue;
+        }
+        if (!VALUE.has(k))
+            return `unknown flag --${k}`;
+        const v = inline ?? argv[++i];
+        if (v === undefined || v === '')
+            return `--${k} needs a value`;
+        o.flags.set(k, [...(o.flags.get(k) ?? []), v]);
+    }
+    return o;
+}
+/** A home given as DIR: the .dexterm folder itself, or a folder holding one (the kit's layout: <dir>/.dexterm + <dir>/dexterm.db). */
+export function resolveHome(dir, env, db) {
+    let d = resolve(dir);
+    if (basename(d) !== '.dexterm' && !existsSync(join(d, 'autotrade')) && existsSync(join(d, '.dexterm')))
+        d = join(d, '.dexterm');
+    const sibling = basename(d) === '.dexterm' ? join(dirname(d), 'dexterm.db') : null;
+    return { dir: d, label: homeLabel(d), db: db ?? (sibling && existsSync(sibling) ? sibling : env.DEXTERM_DB_PATH || defaultDbPath(env)) };
+}
+export async function dashCommand(argv, io, { wait = true } = {}) {
+    const o = parse(argv);
+    if (typeof o === 'string') {
+        io.stderr.write(`dexterm dash: ${o}\n\n${DASH_HELP}\n`);
+        return 2;
+    }
+    if (o.bools.has('help') || o._[0] === 'help') {
+        io.stdout.write(`${DASH_HELP}\n`);
+        return 0;
+    }
+    if (o._.length) {
+        io.stderr.write(`dexterm dash: unexpected argument ${o._[0]}\n\n${DASH_HELP}\n`);
+        return 2;
+    }
+    const db = o.flags.get('db')?.[0];
+    const homes = (o.flags.get('home') ?? [dextermHome(io.env)]).map((h) => resolveHome(h, io.env, db));
+    const books = (o.flags.get('books') ?? []).map((b) => resolve(b));
+    const baseline = o.flags.get('baseline')?.[0] ?? null;
+    if (o.bools.has('json')) {
+        io.stdout.write(`${JSON.stringify(collectDash({ homes, books, baseline }), null, 1)}\n`);
+        return 0;
+    }
+    const out = o.flags.get('export')?.[0];
+    if (out) {
+        const files = exportSnapshot(collectDash({ homes, books, baseline }), resolve(out), { redactMints: o.bools.has('redact-mints') });
+        io.stdout.write(`snapshot written to ${resolve(out)}: ${files.join(', ')}\nIt is a static read-only copy of what this machine shows now. Publishing it is your decision; check it first. Not financial advice.\n`);
+        return 0;
+    }
+    const port = Number(o.flags.get('port')?.[0] ?? DASH_PORT);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        io.stderr.write(`dexterm dash: --port must be 0-65535\n`);
+        return 2;
+    }
+    let server;
+    try {
+        server = await startDashServer({ homes, books, baseline, allowHosts: o.flags.get('allow-host') ?? [] }, port);
+    }
+    catch (e) {
+        io.stderr.write(`dexterm dash: cannot listen on 127.0.0.1:${port} (${e.code ?? e}); try --port N\n`);
+        return 1;
+    }
+    const addr = server.address();
+    const p = typeof addr === 'object' && addr ? addr.port : port;
+    io.stdout.write(`dexterm dash: http://127.0.0.1:${p}/  (reading ${homes.map((h) => h.label).join(', ')}${books.length ? ` + ${books.length} books file(s)` : ''}; loopback only, read-only; Ctrl-C stops)\nPaper trading, not financial advice.\n`);
+    if (!wait) {
+        server.close();
+        return 0;
+    }
+    await new Promise((done) => { const stop = () => { server.close(() => done()); }; process.once('SIGINT', stop); process.once('SIGTERM', stop); });
+    return 0;
+}

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

@@ -204,6 +204,7 @@ export function defaultDeps(env = process.env, isTTY = process.stdout.isTTY ===
         claude: () => claudeProbe(),
         codex: () => codexProbe(4000, env),
         ollama: () => ollamaFacts(env),
+        classifier: () => classifierFacts(env),
         analystEngine: env.DEXTERM_ANALYST_ENGINE ?? loadConfig(dextermHome(env)).config.analyst?.engine ?? null,
         probe: (url) => livingProbe(url),
         checkWritable: writableProbe,
@@ -325,6 +326,12 @@ export async function runDoctor(deps) {
     // 3c. Local engine (task-1543): the user's own Ollama on this machine, the model, tool calling, context, profile.
     if (ol)
         checks.push(ollamaCheck(ol, claude !== 'missing' || codexUsable));
+    // 3d. Classification model (task-1822, EXPERIMENTAL): hardware tier + the picked model. Never fails the doctor.
+    if (deps.classifier) {
+        const cf = await deps.classifier().catch(() => null);
+        if (cf)
+            checks.push(classifierCheck(cf));
+    }
     // 4b. Login with X (optional, task-1357): the user's own X app + login unlock X posts in the SOCIAL panel / TRENDING.
     {
         const xs = new XTokenStore({ env: deps.env });
@@ -471,6 +478,33 @@ export function renderDoctor(result, opts = {}) {
         lines.push(paint(`${fails} check${fails === 1 ? '' : 's'} failed — fix the ✗ lines above, then re-run \`dexterm doctor\`.`, color ? ANSI.fail : ''));
     return lines.join('\n');
 }
+/** task-1822: what `dexterm classifier doctor` says, as one doctor line. */
+export async function classifierFacts(env = process.env) {
+    const { describeHardware, detectHardware, loadClassifierConfig, providerFromConfig, recommendTier } = await import('../../classifier/src/index.js');
+    const hw = await detectHardware();
+    const rec = recommendTier(hw);
+    const c = loadClassifierConfig(env).config;
+    let st = { ready: false, detail: '' };
+    let model = c.provider;
+    try {
+        const p = providerFromConfig(c, c.provider, { env });
+        model = p.model();
+        st = await p.status();
+    }
+    catch (e) {
+        st = { ready: false, detail: e.message };
+    }
+    return { hardware: describeHardware(hw), recommended: rec.model, bestQuality: rec.bestQuality, why: rec.why, provider: c.provider, model, ready: st.ready, detail: st.detail };
+}
+export function classifierCheck(f) {
+    const tier = f.recommended ? `recommended model here: ${f.recommended}${f.bestQuality ? ` (best quality: ${f.bestQuality})` : ''}` : 'recommended: the built-in scores';
+    const name = 'Classification model (experimental)';
+    if (f.provider === 'heuristic')
+        return { name, status: 'pass', detail: `built-in scores (no download) · ${f.hardware} · ${tier}` };
+    if (f.ready)
+        return { name, status: 'pass', detail: `${f.provider} ${f.model} ready · ${tier}` };
+    return { name, status: 'warn', detail: `${f.provider} ${f.model} not ready: ${f.detail}`, fix: f.provider === 'kev-local' ? `dexterm classifier pull ${f.model}, then dexterm classifier serve (answers fall back to the built-in scores meanwhile)` : 'dexterm classifier doctor' };
+}
 /**
  * The Ollama line (task-1543). Optional while claude/codex can run the analyst; a warning with the 2-minute
  * setup when nothing can, or when the user chose ollama and it is not ready.

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

@@ -20,7 +20,7 @@ export const LEDGER_HELP = `dexterm ledger: the unified trade ledger (paper, age
   dexterm ledger sync [--json]                                append what the sources hold to the ledger file
   dexterm ledger verify [--json]                              recompute the ledger file's sha256 chain
 
-  filters: --source paper|desk|autotrade|live  --mode paper|devnet|live  --strategy ID[@VERSION|@HASH]  --profile P
+  filters: --source paper|desk|autotrade|live  --mode paper|devnet|live|real  --strategy ID[@VERSION|@HASH]  --profile P
            --exit REASON  --mint MINT  --run RUN_ID  --account ID  --days N  --status open|closed  --wallet-db PATH
 
   The file is $DEXTERM_HOME/ledger/trades.jsonl (default ~/.dexterm). PAPER rows are simulated; filter by --mode
@@ -95,9 +95,11 @@ function banner(v, rows) {
             out.push(`  ! ${s.problem}`);
     const modes = [...new Set(rows.map((t) => t.walletMode))];
     if (modes.length > 1)
-        out.push('  PAPER, DEVNET and LIVE trades are mixed here: use --mode before comparing results.');
+        out.push('  PAPER, REAL, DEVNET and LIVE trades are mixed here: use --mode before comparing results.');
     else if (modes[0] === 'paper')
         out.push('  PAPER (simulated) trades.');
+    else if (modes[0] === 'real')
+        out.push('  REAL-mode trades: dexterm modelled the trades it signalled to your executor; your executor\'s receipts are the real fills.');
     return out;
 }
 function tradesTable(rows) {

package/dist/packages/cli/src/live/screens/token-live.js

@@ -19,6 +19,7 @@ import { launchIntelCells, holderTags } from "../intel.js";
 import { devBookOf, devRows } from "../dev-history.js";
 import { EX_POOL_TAGS } from '../../../../data/src/index.js';
 import { layoutFor } from "../../custom.js";
+import { narrativeCell } from "../../narratives.js";
 import { chartMode, chartTitle, priceModeOf, chartAxisOf, chartMarkersOn, mcapAt, positionPriceCells, levelCell, supplyRatio } from "../../display.js";
 const dash = '—';
 const EX_POOL_TAG_SET = EX_POOL_TAGS;
@@ -211,6 +212,9 @@ export function renderTokenLive(c, state, v) {
             ['RugCheck score', ...(v.rug === null || v.rug.score === null ? na(v.panels.rugcheck.state === 'error' ? `unavailable: ${v.panels.rugcheck.reason ?? ''}`.trim() : dash) : [`${Math.round(v.rug.score)}/100`, v.rug.score < 30 ? 'ok' : v.rug.score < 60 ? 'warn' : 'bad'])],
             ['GoPlus', ...goplusRow(v)],
             ...devTail,
+            // task-1818 (EXPERIMENTAL): the coin's narrative from the already-built tracker (measured heat, not advice). Never builds
+            // one here (the 26 h replay runs only from N → n); warn = copy-cat saturated or fading/dead, else neutral na (never a green ok).
+            ['Narrative', ...narrativeCell(state, v.mint)],
         ];
         for (const [label, val0, lvl] of fitRows(rows, sb.y + sb.h - sy)) {
             if (sy >= sb.y + sb.h)

package/dist/packages/cli/src/live/signals.js

@@ -69,6 +69,8 @@ export class LiveSignalsLive {
     logByMint = new Map();
     /** Signals emitted this session (all mints), newest last — a cheap counter/feed for the smoke script + tests. */
     emitted = [];
+    /** task-1427: extra read-only listeners (the MCP follow session forwards each signal to the spectator hub). */
+    listeners = new Set();
     constructor(opts = {}) {
         this.engine = new LiveSignalsEngine({ thresholds: opts.thresholds });
         this.now = opts.now ?? (() => Date.now());
@@ -86,6 +88,12 @@ export class LiveSignalsLive {
             this.logByMint.set(s.mint, arr);
             this.emitted.push(s);
             this.onSignal?.(s);
+            for (const l of this.listeners) {
+                try {
+                    l(s);
+                }
+                catch { /* a listener never breaks the engine */ }
+            }
         }
         return sigs;
     }