dexterm-cli 0.1.7 → 0.2.1

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

@@ -47,6 +47,7 @@ import { recordLarpVerdict } from "./larp-record.js";
 import { newAutotradeUi, defaultDeps as autotradeDeps, autotradeCapturing, autotradeTick, reloadList as autotradeReload, refreshRunner as autotradeRefreshRunner } from "./screens/autotrade-ui.js";
 import { autotradeAction, autotradeKey } from "./screens/autotrade-keys.js";
 import { workerJobs as autotradeWorkerJobs } from "./screens/autotrade-worker.js";
+import { narrativesUiOf, kickNarratives, heatRows, drillDetail } from "./narratives.js";
 import { rulesUiOf, rulesTick, rulesMove, beginRuleInput, saveRuleInput, dryRunNow, removeSelectedRule, toggleSelectedRule, dismissSelectedProposal, actOnSelectedProposal, RULE_INPUT_MAX } from "./rules.js";
 import { buildNotifier, hasPushChannel } from "./alerts/notifier.js";
 import { copyAlertToDelivery } from "./alerts/format.js";
@@ -306,12 +307,16 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   dexterm kb list|show|new|edit|check|reset|path     your knowledge-base entries (~/.dexterm/kb/entries) over the bundled 18
   dexterm skill list|show|new|edit|check|reset|path  your analyst skills (~/.dexterm/skills) over the bundled ones (read tools only)
   dexterm narrative [--window 1h|24h] [--summary]  the narrative board over recorded history (no network, no model)
+  dexterm narratives [top|detail ID|of MINT|export]  EXPERIMENTAL memes + narratives tracker over recorded history: themes, heat, lifecycle (measured heat, not advice)
   dexterm backtest [--subject heuristic|pack_verdicts] [--horizon SEC]  honest rug-model metrics over recorded outcomes (no network, no model)
   dexterm ledger trades|positions|summary|equity|compare|export|card|sync|verify  the unified trade ledger: paper, agent desk, autotrade runs (no network; 'dexterm ledger help')
+  dexterm dash [--port N] [--home DIR] [--baseline ID] [--export DIR]  your strategies' performance in a browser on 127.0.0.1 (read-only, no network; 'dexterm dash --help')
   dexterm wallet link|unlink|status|panic|resume  link a Phantom wallet via a local bridge (pubkey only); panic halts autotrade + the paper desk, resume needs a TTY keypress
   dexterm plan propose|list|arm|cancel|journal     conditional order plans (entry/ladder/take-profit/moon bag/stop); arming needs a physical keypress
   dexterm mandate draft|list|arm|revoke            standing capped mandates (paper fills); arming needs a physical keypress — voice/agents can never arm
   dexterm follow add|remove|list|stats|trades|mirror|purge  copy trading tier 1: follow a wallet (your list, local labels), its decoded swaps + FIFO PnL + win rate/early-entry; 'mirror' previews a one-key MIRROR TICKET from the wallet's latest buy (inert; arm in the app)
+  dexterm classifier [list|pick|pull|serve|doctor|bench|try|key]  classification models (EXPERIMENTAL): Kev on your own machine
+                                              (llama.cpp), hosted Jev with your own key, or the built-in heuristic; model estimates, never advice
   dexterm ai [status|engine|model|host|restrictions|probe|ask|agent]  the AI engine: your claude / codex CLI or a free LOCAL model on
                                               your own Ollama (localhost); restriction profiles observe|propose|paper|full ('dexterm ai help')
   dexterm mcp [install <client>|doctor]            read-only MCP server for your own agent; 'install' writes the config for claude-code|claude-desktop|cursor|codex|generic (asks first, idempotent, backs up); 'doctor' verifies the connection
@@ -849,6 +854,12 @@ export async function main(argv, io = process, proc = process) {
         const { runSpectate } = await import("./spectate-cmd.js");
         return runSpectate(argv.slice(1), io);
     }
+    // `dexterm overlay` → the streamer overlay (task-1427): OBS browser-source scenes (agent activity, the coin card,
+    // the PAPER / LIVE PnL card) fed by the read-only spectator stream or a replay; loopback, single-use ticket → token.
+    if (argv[0] === 'overlay') {
+        const { runOverlay } = await import("./overlay-cmd.js");
+        return runOverlay(argv.slice(1), io);
+    }
     // `dexterm recorder <cmd>` → the history recorder's tables: stats, label, prune, export (task-1329). No network.
     if (argv[0] === 'recorder') {
         const { recorderCli } = await import('../../recorder/src/index.js');
@@ -859,11 +870,21 @@ export async function main(argv, io = process, proc = process) {
         const { narrativeCommand } = await import("./narrative-cmd.js");
         return narrativeCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // `dexterm narratives [top|detail ID|of MINT|export]` → the MEMES + NARRATIVES tracker (task-1818, EXPERIMENTAL). No network, no model.
+    if (argv[0] === 'narratives') {
+        const { narrativesCommand } = await import("./narratives-cmd.js");
+        return narrativesCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm ledger …` → the unified trade ledger (task-1530): reads fold the file + the sources; only `sync` writes. No network, no model, no keys.
     if (argv[0] === 'ledger') {
         const { ledgerCommand } = await import("./ledger-cmd.js");
         return ledgerCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // `dexterm dash` → the strategy performance dashboard (task-1749): run ledgers → a page on 127.0.0.1 only. Read-only, no network, no model, no keys.
+    if (argv[0] === 'dash') {
+        const { dashCommand } = await import("./dash-cmd.js");
+        return dashCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm autotrade validate|list|backtest|sweep …` and `dexterm backtest --subject strategy` → the paper autotrade engine (task-1503). No network, no model, no keys.
     if (argv[0] === 'autotrade' || argv[0] === 'backtest') {
         const at = await import("./autotrade-cmd.js");
@@ -1001,6 +1022,11 @@ export async function main(argv, io = process, proc = process) {
         const { aiCommand } = await import("./ai-cmd.js");
         return aiCommand(argv[0] === 'ask' ? ['ask', ...argv.slice(1)] : argv.slice(1), { stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // task-1822: `dexterm classifier …` (pick / pull / serve the classification model; hardware tiers; hosted key).
+    if (argv[0] === 'classifier') {
+        const { classifierCommand } = await import("./classifier-cmd.js");
+        return classifierCommand(argv.slice(1), { stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm doctor` → a pre-flight that says whether dexterm will run here and how to fix what won't (task-1305).
     if (argv[0] === 'doctor') {
         const { defaultDeps, runDoctor, renderDoctor } = await import("./doctor.js");
@@ -1433,6 +1459,20 @@ function rulesScreenMove(state, delta) {
     rulesMove(state.rulesUi, delta);
     return true;
 }
+// task-1818: j/k on the N screen's EXPERIMENTAL heat table move its cursor, or the member cursor while drilled in. The theme
+// board (the default mode) keeps the shared state.selected cursor.
+function narrativesMove(state, delta) {
+    const ui = state.narrativesUi;
+    if (state.screen !== 'narrative' || ui?.mode !== 'heat')
+        return false;
+    if (ui.drill) {
+        const n = drillDetail(state)?.memberList.length ?? 0;
+        ui.drill.selected = Math.max(0, Math.min(n - 1, ui.drill.selected + delta));
+        return true;
+    }
+    ui.selected = Math.max(0, Math.min(heatRows(state).length - 1, ui.selected + delta));
+    return true;
+}
 function plansMove(state, delta) {
     if (state.screen !== 'plans' || !state.plansUi)
         return false;
@@ -1519,7 +1559,7 @@ export function applyAction(state, action, stack) {
         // updates the context injected next turn); PgUp/PgDn scroll the chat transcript. On the token
         // screen (QA M12) the movement keys scroll the answer. Keys reach here only when input is NOT focused.
         case 'move.down':
-            if (plansMove(state, 1) || followsMove(state, 1) || rulesScreenMove(state, 1))
+            if (narrativesMove(state, 1) || plansMove(state, 1) || followsMove(state, 1) || rulesScreenMove(state, 1))
                 break;
             if (bubbleMove(state, 1))
                 break;
@@ -1528,7 +1568,7 @@ export function applyAction(state, action, stack) {
             state.selected = Math.min(rows().length - 1, (state.selected || 0) + 1);
             break;
         case 'move.up':
-            if (plansMove(state, -1) || followsMove(state, -1) || rulesScreenMove(state, -1))
+            if (narrativesMove(state, -1) || plansMove(state, -1) || followsMove(state, -1) || rulesScreenMove(state, -1))
                 break;
             if (bubbleMove(state, -1))
                 break;
@@ -1537,7 +1577,7 @@ export function applyAction(state, action, stack) {
             state.selected = Math.max(0, (state.selected || 0) - 1);
             break;
         case 'move.pagedown':
-            if (plansMove(state, PAGE_ROWS) || followsMove(state, PAGE_ROWS) || rulesScreenMove(state, PAGE_ROWS))
+            if (narrativesMove(state, PAGE_ROWS) || plansMove(state, PAGE_ROWS) || followsMove(state, PAGE_ROWS) || rulesScreenMove(state, PAGE_ROWS))
                 break;
             if (analystChatScroll(state, PAGE_ROWS))
                 break;
@@ -1546,7 +1586,7 @@ export function applyAction(state, action, stack) {
             state.selected = Math.min(rows().length - 1, (state.selected || 0) + PAGE_ROWS);
             break;
         case 'move.pageup':
-            if (plansMove(state, -PAGE_ROWS) || followsMove(state, -PAGE_ROWS) || rulesScreenMove(state, -PAGE_ROWS))
+            if (narrativesMove(state, -PAGE_ROWS) || plansMove(state, -PAGE_ROWS) || followsMove(state, -PAGE_ROWS) || rulesScreenMove(state, -PAGE_ROWS))
                 break;
             if (analystChatScroll(state, -PAGE_ROWS))
                 break;
@@ -1555,14 +1595,14 @@ export function applyAction(state, action, stack) {
             state.selected = Math.max(0, (state.selected || 0) - PAGE_ROWS);
             break;
         case 'move.top':
-            if (plansMove(state, -1e9) || followsMove(state, -1e9))
+            if (narrativesMove(state, -1e9) || plansMove(state, -1e9) || followsMove(state, -1e9))
                 break;
             if (chatScroll(state, -1e9))
                 break;
             state.selected = 0;
             break;
         case 'move.bottom':
-            if (plansMove(state, 1e9) || followsMove(state, 1e9))
+            if (narrativesMove(state, 1e9) || plansMove(state, 1e9) || followsMove(state, 1e9))
                 break;
             if (chatScroll(state, 1e9))
                 break;
@@ -1715,6 +1755,10 @@ export function applyAction(state, action, stack) {
                 state.copyUi.detail = null;
                 break;
             } // task-1399: esc closes the wallet detail view before leaving the screen
+            if (state.screen === 'narrative' && state.narrativesUi?.drill) {
+                state.narrativesUi.drill = null;
+                break;
+            } // task-1818: esc in a drill-down returns to the heat table
             const prev = stack.pop();
             if (prev)
                 state.screen = prev;
@@ -1982,6 +2026,46 @@ export function applyAction(state, action, stack) {
             stack.push(state.screen);
             state.screen = 'narrative';
             state.narrative = computeNarrativeView(state, state.narrative?.window ?? '1h');
+            if (state.narrativesUi?.mode === 'heat')
+                kickNarratives(state); // task-1818: back on the heat table → refresh if it is older than 60 s
+            break;
+        }
+        // task-1818: n flips the theme board ⇄ the EXPERIMENTAL heat table. The first flip starts the tracker build (the recorder's
+        // last 26 h, ~30 s; never at app start); the table shows "building…" until it lands, later refreshes come from the tick.
+        case 'narrative.view': {
+            if (state.screen !== 'narrative')
+                break;
+            const ui = narrativesUiOf(state);
+            ui.mode = ui.mode === 'heat' ? 'board' : 'heat';
+            ui.drill = null;
+            if (ui.mode === 'heat')
+                kickNarratives(state);
+            break;
+        }
+        // task-1818: ⏎ on the heat table drills into the selected narrative; ⏎ on a member opens that coin's token screen (live
+        // mode; fixtures say so). On the theme board ⏎ keeps its old meaning (the shared `open`).
+        case 'narrative.drill': {
+            if (state.screen !== 'narrative')
+                break;
+            const ui = state.narrativesUi;
+            if (ui?.mode !== 'heat')
+                return applyAction(state, 'open', stack);
+            if (!ui.drill) {
+                const r = heatRows(state)[ui.selected];
+                if (r)
+                    ui.drill = { id: r.id, selected: 0 };
+                break;
+            }
+            const m = drillDetail(state)?.memberList[ui.drill.selected];
+            if (!m)
+                break;
+            if (!live) {
+                state.pendingToast = `token detail needs live mode (${m.symbol} ${m.mint.slice(0, 8)}…)`;
+                break;
+            }
+            live.openToken(seedForMint(state, live, m.mint, m.symbol));
+            stack.push(state.screen);
+            state.screen = 'token';
             break;
         }
         case 'narrative.window': {
@@ -4283,6 +4367,11 @@ export function interactive(state, io, depth, args, proc = process) {
             // execution moment, pause / kill) draws over this terminal while it follows. Calm mode = reduced motion.
             state.agentHud = { story: followSession.story, clock: () => Date.now(), dataLabel: args.replay ? 'REPLAY DATA' : null };
             void followSession.start();
+            // task-1427: the open coin's live holder/rug signals ride the spectator stream too (the streamer overlay's coin card).
+            {
+                const fs = followSession;
+                state.live?.signals.listeners.add((sig) => fs.liveFlag(sig));
+            }
             if (size()[1] < HUD_MIN_H)
                 say('following agents over MCP · ctrl+p pause · ctrl+k stop · any key takes over', 'ai', 6);
             if (agentPaper)
@@ -6169,6 +6258,9 @@ export function interactive(state, io, depth, args, proc = process) {
                         say(state.updateNotice, 'info', 8);
                         state.updateNotice = null;
                     }
+                    // task-1818: refresh the EXPERIMENTAL narratives tracker at most every 60 s while its heat table is on screen.
+                    if (state.screen === 'narrative' && state.narrativesUi?.mode === 'heat' && !state.paused)
+                        kickNarratives(state);
                     // task-1508: the autotrade screen re-reads the paper runner's status file every 2 s while it is open.
                     if (state.screen === 'autotrade' && state.autotradeUi)
                         autotradeTick(state.autotradeUi);

package/dist/packages/cli/src/mcp-follow.js

@@ -116,7 +116,10 @@ export class McpFollowSession {
         };
         this.follow = new FollowController({ controls, activityCap: Math.max(1, opts.activityCap ?? 200) });
         this.story = new AgentStory(this.agentLabel);
-        this.hub.on((ev) => { this.follow.apply(ev); this.story.apply(ev); });
+        // task-1427: a live signal the TERMINAL fired (liveFlag) rides the hub for the stream only; it is not an agent call
+        // or an agent thought, so the follow view and the story never fold it (the story would show a note as a thought).
+        this.hub.on((ev) => { if (ev.phase === 'note' && ev.tool === 'live_signal')
+            return; this.follow.apply(ev); this.story.apply(ev); });
     }
     /** Arm the rendezvous (so a `dexterm mcp` server starts emitting) and begin tailing. Idempotent. */
     async start() {
@@ -304,6 +307,23 @@ export class McpFollowSession {
         }
         catch { /* ignore */ }
     }
+    /**
+     * task-1427: a live holder / rug signal the owner's terminal fired for a coin (the task-1404 engine) → one `note`
+     * event in the hub, so the streamer overlay's coin card can show it with its age. Only while armed (an agent is
+     * being followed); it describes data the terminal already read, and carries nothing anyone can act on.
+     */
+    liveFlag(s) {
+        if (!this.armed)
+            return;
+        const detail = sanitizeDetail({ coin: { mint: s.mint }, liveFlags: [{ kind: s.kind, level: s.level, title: s.title, text: s.text, source: s.source, at: s.at, ageSec: Math.max(0, s.dataAgeMs / 1000), stale: s.stale }] });
+        if (!detail?.liveFlags)
+            return;
+        this.hub.emit({ phase: 'note', agent: this.currentAgent, transport: 'mcp', tool: 'live_signal', summary: `${s.title}: ${s.text}`.slice(0, 140), detail, ok: true, t: s.at });
+        try {
+            this.opts.onEvent?.();
+        }
+        catch { /* ignore */ }
+    }
     /** True when the terminal should mirror the agent: the agent still has control and is active. */
     canFollow() {
         if (this.follow.controlState !== 'agent')

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

@@ -0,0 +1,147 @@
+// `dexterm narratives [top|detail ID|of MINT|export] [--db PATH] [--json] [--at ISO] [--lookback-h N] [--out FILE]`
+// (task-1818, EXPERIMENTAL). The MEMES + NARRATIVES tracker over the history recorder: coins clustered by the theme
+// their name/ticker carries, with per-window heat metrics and lifecycle states. Keyless, local, read-only on the DB.
+// Measured heat, never advice.
+import { DatabaseSync } from 'node:sqlite';
+import { writeFileSync } from 'node:fs';
+import { defaultDbPath } from '../../data/src/index.js';
+import { trackerFromRecorder, toExport, renderTable, coinField, embedderFromEnv, HEAT_NOTE, LIFECYCLE_RULES } from '../../narratives/src/index.js';
+export const NARRATIVES_HELP = `dexterm narratives: the MEMES + NARRATIVES tracker (task-1818, EXPERIMENTAL). No network, no model, no key.
+
+  dexterm narratives [top]          the hottest narratives (rank = memetic traction score)
+  dexterm narratives detail ID      one narrative: windows, lifecycle rule, member coins in spawn order
+  dexterm narratives of MINT        which narrative a coin belongs to
+  dexterm narratives export [--out FILE]   the dexterm-narratives/1 JSON the strategy tracker page reads
+
+  --db PATH        defaults to DEXTERM_DB_PATH, else ~/.local/share/dexterm/dexterm.db (opened read-only)
+  --at ISO         replay up to this time instead of now (point-in-time: only rows recorded before it)
+  --lookback-h N   hours of history to replay (default 26)
+  --limit N        rows (default 20)
+  --json           machine-readable output
+
+  Coins are grouped by what their name/ticker says (ticker puns, animals, celebrities/politics, AI agents,
+  seasonal, copy-cats of a runner); a coin needs no real project to belong. Lifecycle states:
+${LIFECYCLE_RULES.map(([s, r]) => `    ${s.padEnd(9)} ${r}`).join('\n')}
+  ${HEAT_NOTE}
+  Embedder: DEXTERM_NARRATIVE_EMBEDDER=lexical (default, built in) | minilm (needs DEXTERM_EMBED_MODULE_DIR) | ollama[:model].`;
+function parse(argv) {
+    const opts = {};
+    const pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) {
+            pos.push(a);
+            continue;
+        }
+        const k = a.slice(2);
+        const v = argv[i + 1];
+        if (v !== undefined && !v.startsWith('--') && k !== 'json' && k !== 'help') {
+            opts[k] = v;
+            i++;
+        }
+        else
+            opts[k] = true;
+    }
+    return { pos, opts };
+}
+export async function narrativesCommand(argv, io) {
+    const { pos, opts } = parse(argv);
+    if (opts.help || pos[0] === 'help') {
+        io.stdout.write(NARRATIVES_HELP + '\n');
+        return 0;
+    }
+    const cmd = pos[0] ?? 'top';
+    if (!['top', 'detail', 'of', 'export'].includes(cmd)) {
+        io.stderr.write(`dexterm narratives: unknown command "${cmd}" (top | detail ID | of MINT | export)\n`);
+        return 2;
+    }
+    const path = typeof opts.db === 'string' ? opts.db : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    if (path === ':memory:') {
+        io.stderr.write('dexterm narratives: an in-memory DB has no history\n');
+        return 2;
+    }
+    const at = typeof opts.at === 'string' ? Date.parse(opts.at) : Date.now();
+    if (!Number.isFinite(at)) {
+        io.stderr.write('dexterm narratives: --at needs an ISO time\n');
+        return 2;
+    }
+    const lookbackH = typeof opts['lookback-h'] === 'string' ? Number(opts['lookback-h']) : 26;
+    if (!(Number.isFinite(lookbackH) && lookbackH > 0)) {
+        io.stderr.write('dexterm narratives: --lookback-h needs a number of hours above 0\n');
+        return 2;
+    }
+    const limitN = typeof opts.limit === 'string' ? Math.floor(Number(opts.limit)) : 20;
+    if (!Number.isFinite(limitN) || limitN < 1) {
+        io.stderr.write('dexterm narratives: --limit needs a whole number of 1 or more\n');
+        return 2;
+    }
+    const limit = Math.min(200, limitN);
+    let db = null;
+    try {
+        db = new DatabaseSync(path, { readOnly: true });
+        if (!db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'token_snapshots'").get()) {
+            io.stderr.write(`dexterm narratives: no recorded history in ${path} (run the app with the recorder on first)\n`);
+            return 2;
+        }
+        const t0 = performance.now();
+        const tr = await trackerFromRecorder(db, { now: at, lookbackMs: lookbackH * 3_600_000, embedder: embedderFromEnv(io.env) });
+        const ms = Math.round(performance.now() - t0);
+        if (cmd === 'export') {
+            const ex = toExport(tr, { limit: Math.max(limit, 50), now: at });
+            const json = JSON.stringify(ex, null, 1) + '\n';
+            if (typeof opts.out === 'string') {
+                writeFileSync(opts.out, json);
+                io.stdout.write(`wrote ${opts.out}: ${ex.narratives.length} narratives over ${ex.coins} coins (${ms} ms)\n`);
+            }
+            else
+                io.stdout.write(json);
+            return 0;
+        }
+        if (cmd === 'detail' || cmd === 'of') {
+            const key = pos[1];
+            if (!key) {
+                io.stderr.write(`dexterm narratives ${cmd}: needs ${cmd === 'detail' ? 'a narrative id' : 'a mint'}\n`);
+                return 2;
+            }
+            const n = cmd === 'of' ? tr.narrativeOf(key) : null;
+            if (cmd === 'of' && !n) {
+                io.stdout.write(opts.json ? JSON.stringify({ mint: key, narrative: null, note: 'not recorded in the lookback window' }) + '\n' : `${coinField(null)} (no recorded sighting in the last ${lookbackH} h)\n`);
+                return 0;
+            }
+            const d = tr.detail(cmd === 'of' ? n.narrative : key);
+            if (!d) {
+                io.stderr.write(`dexterm narratives: unknown narrative id ${key}\n`);
+                return 2;
+            }
+            if (opts.json) {
+                io.stdout.write(JSON.stringify(cmd === 'of' ? { ...n, detail: d } : d, null, 1) + '\n');
+                return 0;
+            }
+            if (n)
+                io.stdout.write(coinField(n) + '\n');
+            io.stdout.write(renderTable([d], 150) + '\n\n');
+            io.stdout.write(`lifecycle rule: ${d.lifecycleRule}\nmembers (spawn order, newest ${Math.min(limit, d.memberList.length)} of ${d.memberList.length}):\n`);
+            for (const m of d.memberList.slice(-limit))
+                io.stdout.write(`  #${String(m.spawn).padEnd(4)} ${m.symbol.padEnd(12)} ${m.name.slice(0, 28).padEnd(28)} ${m.x == null ? '   —' : (m.x.toFixed(2) + 'x').padStart(7)}  ${m.mint}\n`);
+            return 0;
+        }
+        const rows = tr.top(limit);
+        if (opts.json) {
+            io.stdout.write(JSON.stringify(toExport(tr, { limit, now: at }), null, 1) + '\n');
+            return 0;
+        }
+        io.stdout.write(`NARRATIVES (EXPERIMENTAL) · as of ${tr.lastTickAt ? new Date(tr.lastTickAt).toISOString() : '—'} · ${tr.coins.size} coins over ${lookbackH} h · embedder ${tr.embedder.id} · ${ms} ms\n`);
+        io.stdout.write(renderTable(rows, 150) + '\n');
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`dexterm narratives: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}

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

@@ -0,0 +1,114 @@
+import { NarrativeTracker, RecorderNarratives, coinField, embedderFromEnv, sanitize } from '../../narratives/src/index.js';
+/** Later refreshes run at most this often (the first one runs on open). */
+export const NARRATIVES_REFRESH_MS = 60_000;
+/** Rows in the heat table. */
+export const HEAT_LIMIT = 50;
+export const UNTRUSTED_NOTE = 'names are untrusted, shown control-stripped';
+const services = new WeakMap();
+const screenTrackers = new WeakMap();
+export function narrativesUiOf(state) {
+    if (!state.narrativesUi)
+        state.narrativesUi = { mode: 'board', selected: 0, drill: null, busy: false, error: null, source: null, refreshedAt: 0, buildMs: null };
+    return state.narrativesUi;
+}
+const dbOf = (state) => state.live?.recorder?.database ?? null;
+export const narrativesSource = (state) => (dbOf(state) ? 'recorded' : 'screen');
+/** The tracker ALREADY built for this state, or null. Never builds (the coin pane / rules / renders call this). */
+export function currentTracker(state) {
+    const db = dbOf(state);
+    return (db ? services.get(db)?.tracker ?? null : null) ?? screenTrackers.get(state) ?? null;
+}
+/** Install a tracker for a state with no recorder DB (tests; the screen-rows fallback uses the same slot). */
+export function setNarrativeTracker(state, tr) { if (tr)
+    screenTrackers.set(state, tr);
+else
+    screenTrackers.delete(state); }
+/**
+ * Build or refresh the tracker. Recorder DB: the per-process RecorderNarratives (first call = the 26 h replay, later
+ * calls replay only new rows; it self-throttles to NARRATIVES_REFRESH_MS). No DB: the visible screener rows are fed
+ * to a per-state tracker (first sightings once, a sample per row each call) and ticked now.
+ */
+export async function ensureNarratives(state, now = Date.now()) {
+    const db = dbOf(state);
+    if (db) {
+        let svc = services.get(db);
+        if (!svc)
+            services.set(db, (svc = new RecorderNarratives(db, { embedder: embedderFromEnv(process.env), minRefreshMs: NARRATIVES_REFRESH_MS })));
+        return svc.refresh(now);
+    }
+    const rows = state.screener.rows.filter((r) => r.mint && !r.skeleton);
+    let tr = screenTrackers.get(state) ?? null;
+    if (!rows.length)
+        return tr;
+    if (!tr)
+        screenTrackers.set(state, (tr = new NarrativeTracker()));
+    const at = (r) => Math.min(now, r.fetchedAt ?? now);
+    await tr.addCoins(rows.map((r) => ({ mint: r.mint, t: at(r), symbol: r.symbol, name: r.name })));
+    for (const r of rows)
+        tr.addSample({ mint: r.mint, t: at(r), price: r.price, liq: r.liq, mcap: r.mcap, vol5m: r.vol5m, vol1h: r.vol1h, vol6h: r.vol6h, vol24h: r.vol24 });
+    tr.tick(now, true);
+    return tr;
+}
+/**
+ * Start a build/refresh in the background unless one is running or the last finished < NARRATIVES_REFRESH_MS ago
+ * (`force` skips the age check). The work starts on a short timer so the "building…" frame paints first; the recorder
+ * replay then yields to the event loop every 40 ms (RecorderNarratives), so frames keep drawing. Returns whether it started.
+ */
+export function kickNarratives(state, opts = {}) {
+    const ui = narrativesUiOf(state);
+    const now = opts.now ?? Date.now();
+    if (ui.busy)
+        return false;
+    if (!opts.force && ui.refreshedAt && now - ui.refreshedAt < NARRATIVES_REFRESH_MS)
+        return false;
+    ui.busy = true;
+    ui.error = null;
+    const run = () => {
+        const t0 = Date.now();
+        void ensureNarratives(state, Date.now())
+            .then(() => { ui.source = narrativesSource(state); ui.buildMs = Date.now() - t0; })
+            .catch((e) => { ui.error = e instanceof Error ? e.message : String(e); })
+            .finally(() => { ui.busy = false; ui.refreshedAt = Date.now(); opts.onDone?.(); });
+    };
+    const tm = setTimeout(run, opts.delayMs ?? 40);
+    tm.unref?.();
+    return true;
+}
+/** The heat table's rows (control-stripped labels). The screen-rows fallback has no history, so solo coins show too. */
+export function heatRows(state) {
+    const tr = currentTracker(state);
+    if (!tr)
+        return [];
+    return tr.top(HEAT_LIMIT, { minMembers: narrativesSource(state) === 'screen' ? 1 : 2 }).map((s) => sanitize(s));
+}
+/** The drilled narrative (with its member list in spawn order), or null. */
+export function drillDetail(state) {
+    const id = state.narrativesUi?.drill?.id;
+    const tr = currentTracker(state);
+    if (!id || !tr)
+        return null;
+    const d = tr.detail(id);
+    if (d)
+        d.memberList.sort((a, b) => a.spawn - b.spawn);
+    return d;
+}
+/** One coin's narrative from the already-built tracker (null = not built or not tracked). */
+export function narrativeFor(state, mint) {
+    return currentTracker(state)?.narrativeOf(mint) ?? null;
+}
+/** The coin pane's Narrative row value + level: warn when copy-cat saturated or fading/dead, else the neutral na (heat is
+ *  never shown as a green "ok": it is not a quality mark of the coin). */
+export function narrativeCell(state, mint) {
+    if (!currentTracker(state))
+        return ['open N → n to build', 'na'];
+    const n = narrativeFor(state, mint);
+    const text = coinField(n).replace(/^narrative: /, '');
+    if (!n)
+        return [text, 'na'];
+    return [text, n.saturated || n.lifecycle === 'fading' || n.lifecycle === 'dead' ? 'warn' : 'na'];
+}
+/** The rules' narrative fields for one coin (all null when not built / not tracked; a rule clause on them is then false). */
+export function narrativeRuleFields(state, mint) {
+    const n = narrativeFor(state, mint);
+    return { narrativeRank: n?.rank ?? null, narrativeScore: n?.score ?? null, narrativeLifecycle: n?.lifecycle ?? null, narrativeSaturated: n ? n.saturated : null };
+}