dexterm-cli 0.2.0 → 0.2.2

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 };
+}

package/dist/packages/cli/src/overlay/model.js

@@ -0,0 +1,147 @@
+// dexterm — STREAMER OVERLAY model (task-1427). A pure fold of spectator events into the three OBS scenes:
+//   activity  the agent's recent calls (redacted), newest first
+//   coin      the coin the agent is on: name, LARP evidence + verdict, a top-10 holder bar, live signals with ages
+//   pnl       the agent's PAPER fills on that coin (drawn by the task-1407 card renderer, see overlay/pnl.ts)
+//
+// Honesty by construction:
+//   - every event is passed through redactSpectatorEvent HERE, whatever its source already did, so a full address
+//     or key can never reach a scene (addresses become head…tail; key material becomes [key]);
+//   - every figure is copied from an event; nothing is estimated. Each scene carries the age of its data;
+//   - a replayed recording is SAMPLE DATA: `sample` is set once by the caller and every scene view carries it.
+// No I/O, no clock (callers pass `now`), no control surface: the overlay can only describe what already happened.
+import { redactSpectatorEvent } from '../../../agents/src/index.js';
+/** How many activity rows a scene keeps (OBS lower thirds are short). */
+export const OVERLAY_ACTIVITY_MAX = 8;
+/** Live signals kept on the coin card. */
+export const OVERLAY_FLAGS_MAX = 4;
+export const OVERLAY_SCENES = ['activity', 'coin', 'pnl'];
+export function emptyOverlayState(sample) {
+    return { sample, lastEventAt: null, events: 0, activity: [], coins: new Map(), current: null, paper: new Map(), paperCurrent: null };
+}
+const MASKED_RE = /^[1-9A-HJ-NP-Za-km-z]{4}…[1-9A-HJ-NP-Za-km-z]{4}$/;
+// eslint-disable-next-line no-control-regex
+const UNSAFE_RE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g;
+const clean = (s, max) => (typeof s === 'string' ? s.replace(UNSAFE_RE, '').slice(0, max) : '');
+const finite = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+/** Fold one event (any source) into the state. Returns the redacted copy that was folded. */
+export function foldOverlay(state, raw) {
+    const ev = redactSpectatorEvent(raw);
+    const t = finite(ev.t) ?? 0;
+    state.events++;
+    state.lastEventAt = state.lastEventAt === null ? t : Math.max(state.lastEventAt, t);
+    if (ev.phase !== 'note' || ev.tool !== 'live_signal') {
+        state.activity.unshift({
+            t, agent: clean(ev.agent, 24) || 'agent', phase: clean(ev.phase, 12), tool: clean(ev.tool ?? '', 28),
+            summary: clean(ev.summary ?? '', 120), ok: ev.ok !== false, dataAgeSec: finite(ev.dataAgeSec),
+        });
+        if (state.activity.length > OVERLAY_ACTIVITY_MAX)
+            state.activity.length = OVERLAY_ACTIVITY_MAX;
+    }
+    const d = ev.detail ?? {};
+    const age = finite(ev.dataAgeSec) ?? 0;
+    const mint = [d.coin?.mint, d.fill?.mint, d.ticket?.mint, ev.nav?.mint].find((m) => typeof m === 'string' && MASKED_RE.test(m)) ?? null;
+    if (mint) {
+        const c = coin(state, mint, t);
+        if (ev.nav?.mint === mint || d.coin || d.verdict || d.larp || d.holders)
+            state.current = mint;
+        const sym = clean(d.coin?.symbol ?? d.fill?.symbol ?? d.ticket?.symbol ?? '', 16);
+        if (sym && sym !== '?')
+            c.symbol = sym;
+        const px = finite(d.coin?.priceUsd ?? null) ?? finite(d.fill?.priceUsd ?? null);
+        if (px !== null && px > 0)
+            c.priceUsd = { value: px, at: t, ageSec: age };
+        if (d.verdict)
+            c.verdict = { label: clean(d.verdict.label, 18), rug: finite(d.verdict.rug ?? null), at: t, ageSec: age };
+        if (d.larp)
+            c.larp = { flags: Math.max(0, Math.round(d.larp.flags)), items: d.larp.items.slice(0, 4).map((x) => clean(x, 60)), at: t, ageSec: age };
+        if (d.holders && finite(d.holders.top10Pct) !== null) {
+            c.holders = { top10Pct: Math.max(0, Math.min(100, d.holders.top10Pct)), count: finite(d.holders.count ?? null), basis: d.holders.basis === 'raw' ? 'raw' : 'ex-pools', at: t, ageSec: finite(d.holders.ageSec ?? null) ?? age };
+        }
+        for (const f of d.liveFlags ?? []) {
+            // dated on the event's clock: at the event the reading was its own age plus the time since the signal fired
+            // (so a replayed recording, re-timed to the playback clock, keeps its signals' ages consistent)
+            const fat = finite(f.at) ?? t;
+            c.flags.unshift({ kind: clean(f.kind, 16), level: f.level, title: clean(f.title, 24), text: clean(f.text, 120), source: clean(f.source, 24), stale: f.stale === true, at: t, ageSec: Math.max(0, finite(f.ageSec) ?? 0) + Math.max(0, t - fat) / 1000 });
+        }
+        if (c.flags.length > OVERLAY_FLAGS_MAX)
+            c.flags.length = OVERLAY_FLAGS_MAX;
+        if (d.fill && ev.ok !== false) {
+            const f = d.fill;
+            const sol = finite(f.sol), qty = finite(f.qty);
+            if (sol !== null && qty !== null && qty > 0 && (f.side === 'buy' || f.side === 'sell')) {
+                const p = state.paper.get(mint) ?? { mint, symbol: c.symbol ?? '?', fills: [] };
+                p.symbol = c.symbol ?? p.symbol;
+                p.fills.push({ t, side: f.side, sol, qty, priceUsd: finite(f.priceUsd) });
+                if (p.fills.length > 200)
+                    p.fills.splice(0, p.fills.length - 200);
+                state.paper.set(mint, p);
+                state.paperCurrent = mint;
+            }
+        }
+    }
+    return ev;
+}
+function coin(state, mint, t) {
+    let c = state.coins.get(mint);
+    if (!c) {
+        c = { mint, symbol: null, priceUsd: null, verdict: null, larp: null, holders: null, flags: [], lastAt: t };
+        state.coins.set(mint, c);
+        // bounded: a long session touches many coins; keep the 50 most recent
+        if (state.coins.size > 50) {
+            const oldest = [...state.coins.values()].filter((x) => x.mint !== state.current).sort((a, b) => a.lastAt - b.lastAt)[0];
+            if (oldest)
+                state.coins.delete(oldest.mint);
+        }
+    }
+    c.lastAt = Math.max(c.lastAt, t);
+    return c;
+}
+// ------------------------------------------------------------------------------------------------ scene views
+/** Seconds → "12s" / "4m" / "2h" / "3d" (the scenes' age chips). */
+export function fmtAgeShort(sec) {
+    if (sec === null || !Number.isFinite(sec))
+        return '—';
+    const s = Math.max(0, Math.round(sec));
+    return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86_400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86_400)}d`;
+}
+/** The age of a dated value at `now`: how old it was when it arrived plus the time since. */
+export const ageAt = (d, now) => d.ageSec + Math.max(0, now - d.at) / 1000;
+function header(state, newestAgeSec) {
+    return { sample: state.sample, ageSec: newestAgeSec, age: newestAgeSec === null ? 'no data yet' : `data age ${fmtAgeShort(newestAgeSec)}` };
+}
+export function activityView(state, now) {
+    const newest = state.activity[0];
+    return {
+        scene: 'activity',
+        ...header(state, newest ? Math.max(0, now - newest.t) / 1000 + (newest.dataAgeSec ?? 0) : null),
+        rows: state.activity.map((r) => ({
+            when: fmtAgeShort(Math.max(0, now - r.t) / 1000), agent: r.agent, phase: r.phase, tool: r.tool, summary: r.summary, ok: r.ok,
+            dataAge: r.dataAgeSec === null ? null : fmtAgeShort(r.dataAgeSec + Math.max(0, now - r.t) / 1000),
+        })),
+    };
+}
+const fmtUsdPrice = (v) => (v >= 1 ? `$${v.toFixed(4)}` : v >= 0.0001 ? `$${v.toPrecision(4)}` : `$${v.toExponential(2)}`);
+export function coinView(state, now) {
+    const c = state.current ? state.coins.get(state.current) ?? null : null;
+    if (!c)
+        return { scene: 'coin', ...header(state, null), coin: null };
+    const ages = [c.priceUsd, c.verdict, c.larp, c.holders, ...c.flags].filter((x) => !!x).map((x) => ageAt(x, now));
+    return {
+        scene: 'coin',
+        ...header(state, ages.length ? Math.min(...ages) : null),
+        coin: {
+            mint: c.mint,
+            symbol: c.symbol ?? '?',
+            price: c.priceUsd ? { text: fmtUsdPrice(c.priceUsd.value), age: fmtAgeShort(ageAt(c.priceUsd, now)) } : null,
+            verdict: c.verdict ? { label: c.verdict.label, rug: c.verdict.rug === null ? null : `${Math.round(c.verdict.rug * 100)}%`, age: fmtAgeShort(ageAt(c.verdict, now)) } : null,
+            larp: c.larp ? { flags: c.larp.flags, items: c.larp.items, age: fmtAgeShort(ageAt(c.larp, now)) } : null,
+            holders: c.holders ? {
+                top10Pct: +c.holders.top10Pct.toFixed(1),
+                text: `top 10 hold ${c.holders.top10Pct.toFixed(1)}%${c.holders.count !== null ? ` · ${c.holders.count.toLocaleString('en-US')} holders` : ''}`,
+                basis: c.holders.basis === 'ex-pools' ? 'pools, curves, locks and burns left out' : 'every account counted (raw)',
+                age: fmtAgeShort(ageAt(c.holders, now)),
+            } : null,
+            flags: c.flags.map((f) => ({ level: f.level, title: f.title, text: f.text, source: f.source, age: fmtAgeShort(ageAt(f, now)), stale: f.stale })),
+        },
+    };
+}

package/dist/packages/cli/src/overlay/page.js

@@ -0,0 +1,146 @@
+// dexterm — STREAMER OVERLAY page (task-1427): one self-contained HTML document per scene, built for an OBS
+// browser source. The body is transparent (OBS composites it over the stream); the panels carry the cyberspace
+// look in three presets. Everything is inlined under the server's per-page nonce; the script builds the DOM with
+// textContent only (never innerHTML), because every string it shows came from an agent or a token and is untrusted.
+// The page has no controls and sends nothing back: the socket is read-only (see server.ts).
+/** Three presets of the cyberspace look (the app's `cyberspace` theme tokens and two neon variants). */
+export const OVERLAY_THEMES = {
+    cyberspace: { panel: 'rgba(3,9,12,0.86)', edge: '#0c3a24', glow: '#39ff14', text: '#eafff0', muted: '#62c98a', dim: '#3aa866', accent: '#00f0ff', up: '#5dff6e', down: '#ff3b6b', warn: '#f5ff2d' },
+    ice: { panel: 'rgba(2,8,16,0.86)', edge: '#0b3348', glow: '#00f0ff', text: '#e8fbff', muted: '#6cc7dd', dim: '#3f98b0', accent: '#39ff14', up: '#5dff6e', down: '#ff3b6b', warn: '#f5ff2d' },
+    neon: { panel: 'rgba(10,3,16,0.86)', edge: '#3b0f4a', glow: '#ff2bd6', text: '#fff0fc', muted: '#d07ac0', dim: '#a04f93', accent: '#00f0ff', up: '#5dff6e', down: '#ff3b6b', warn: '#f5ff2d' },
+};
+export const OVERLAY_THEME_NAMES = Object.keys(OVERLAY_THEMES);
+const CSS = `
+:root{--panel:__PANEL__;--edge:__EDGE__;--glow:__GLOW__;--text:__TEXT__;--muted:__MUTED__;--dim:__DIM__;--accent:__ACCENT__;--up:__UP__;--down:__DOWN__;--warn:__WARN__}
+html,body{margin:0;padding:0;background:transparent;color:var(--text);font:600 18px/1.35 ui-monospace,SFMono-Regular,Menlo,Consolas,"DejaVu Sans Mono",monospace;overflow:hidden}
+body{padding:12px}
+.grid{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:12px}
+.grid .pnl{grid-column:1 / span 2}
+.scene{background:var(--panel);border:1px solid var(--edge);box-shadow:0 0 0 1px rgba(0,0,0,.4),0 0 18px -6px var(--glow);border-radius:6px;padding:10px 14px;max-width:1200px}
+.head{display:flex;gap:10px;align-items:center;border-bottom:1px solid var(--edge);padding-bottom:6px;margin-bottom:8px;white-space:nowrap}
+.brand{color:var(--glow)}.title{color:var(--muted);letter-spacing:.08em}
+.sp{flex:1}
+.chip{border:1px solid var(--edge);border-radius:3px;padding:0 6px;color:var(--dim);font-size:14px}
+.chip.sample{color:#000;background:var(--warn);border-color:var(--warn)}
+.chip.old{color:var(--warn);border-color:var(--warn)}
+.chip.paper{color:#000;background:var(--warn);border-color:var(--warn)}
+.chip.live{color:#000;background:var(--up);border-color:var(--up)}
+.chip.off{color:var(--down);border-color:var(--down)}
+.row{display:grid;grid-template-columns:3.2em 9em 11em minmax(0,1fr) 4.5em;gap:8px;white-space:nowrap;overflow:hidden}
+.row>*{overflow:hidden;text-overflow:ellipsis}
+.when,.age{color:var(--dim)}.agent{color:var(--accent)}.tool{color:var(--muted)}.bad{color:var(--down)}
+.sym{font-size:34px;color:var(--text)}.mint{color:var(--dim);font-size:14px}
+.kv{display:flex;gap:10px;margin:4px 0;white-space:nowrap}.k{color:var(--dim);min-width:7.5em}.v{overflow:hidden;text-overflow:ellipsis}
+.bar{height:14px;border:1px solid var(--edge);border-radius:2px;background:rgba(0,0,0,.35);margin:3px 0 2px}
+.fill{height:100%;background:linear-gradient(90deg,var(--up),var(--warn) 55%,var(--down))}
+.small{font-size:14px;color:var(--dim)}
+.flag{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.flag.warn,.flag.down{color:var(--down)}.flag.up{color:var(--up)}.flag.info{color:var(--muted)}
+.card{position:relative}.card img{display:block;width:100%;height:auto;image-rendering:pixelated;border-radius:3px}
+.banner{position:absolute;left:0;right:0;top:0;text-align:center;font-size:22px;line-height:30px;color:#000;background:var(--warn);letter-spacing:.12em;border-radius:3px 3px 0 0}
+.empty{color:var(--dim)}
+.foot{margin-top:6px;color:var(--dim);font-size:13px}
+`;
+const JS = `
+(function(){
+  'use strict';
+  var PAGE = document.querySelector('meta[name="dexterm-page"]').content;
+  var WS_URL = document.querySelector('meta[name="dexterm-ws"]').content;
+  var SCENES = PAGE === 'all' ? ['coin','activity','pnl'] : [PAGE];
+  var TITLES = { activity: 'AGENT ACTIVITY', coin: 'COIN', pnl: 'PnL' };
+  var root = document.getElementById('root');
+  if (PAGE === 'all') root.className = 'grid';
+  var boxes = {};
+  function el(tag, cls, text){ var e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined && text !== null) e.textContent = String(text); return e; }
+  SCENES.forEach(function(s){
+    var box = el('section', 'scene ' + s);
+    var head = el('div', 'head');
+    head.appendChild(el('span', 'brand', '\\u25c6 dexterm'));
+    head.appendChild(el('span', 'title', TITLES[s]));
+    head.appendChild(el('span', 'sp'));
+    var stamp = el('span', 'chip'); stamp.hidden = true; head.appendChild(stamp);
+    var sample = el('span', 'chip sample', 'SAMPLE DATA \\u00b7 REPLAY'); sample.hidden = true; head.appendChild(sample);
+    var age = el('span', 'chip age', 'waiting for data'); head.appendChild(age);
+    var conn = el('span', 'chip off', 'disconnected'); conn.hidden = true; head.appendChild(conn);
+    var body = el('div', 'body'); body.appendChild(el('div', 'empty', 'waiting for the agent\\u2026'));
+    var foot = el('div', 'foot', 'read-only \\u00b7 addresses redacted \\u00b7 not financial advice \\u00b7 dexterm.xyz');
+    box.appendChild(head); box.appendChild(body); box.appendChild(foot);
+    root.appendChild(box);
+    boxes[s] = { body: body, age: age, sample: sample, stamp: stamp, conn: conn };
+  });
+  function header(b, v){
+    b.sample.hidden = !v.sample;
+    b.age.textContent = v.age;
+    b.age.className = 'chip age' + (v.ageSec !== null && v.ageSec > 120 ? ' old' : '');
+  }
+  function clear(n){ while (n.firstChild) n.removeChild(n.firstChild); }
+  function kv(k, v, extra){ var r = el('div', 'kv'); r.appendChild(el('span', 'k', k)); r.appendChild(el('span', 'v', v)); if (extra) r.appendChild(el('span', 'age', extra)); return r; }
+  var render = {
+    activity: function(b, v){
+      clear(b.body);
+      if (!v.rows.length) { b.body.appendChild(el('div', 'empty', 'no agent calls yet')); return; }
+      v.rows.forEach(function(r){
+        var row = el('div', 'row' + (r.ok ? '' : ' bad'));
+        row.appendChild(el('span', 'when', r.when));
+        row.appendChild(el('span', 'agent', r.agent));
+        row.appendChild(el('span', 'tool', r.tool || r.phase));
+        row.appendChild(el('span', 'sum', r.summary));
+        row.appendChild(el('span', 'age', r.dataAge ? r.dataAge + ' old' : ''));
+        b.body.appendChild(row);
+      });
+    },
+    coin: function(b, v){
+      clear(b.body);
+      var c = v.coin;
+      if (!c) { b.body.appendChild(el('div', 'empty', 'the agent has not opened a coin yet')); return; }
+      var top = el('div', 'kv'); top.appendChild(el('span', 'sym', '$' + c.symbol)); top.appendChild(el('span', 'mint', c.mint)); b.body.appendChild(top);
+      if (c.price) b.body.appendChild(kv('PRICE', c.price.text, c.price.age + ' old'));
+      b.body.appendChild(c.verdict ? kv('VERDICT', c.verdict.label + (c.verdict.rug ? ' \\u00b7 rug heuristic ' + c.verdict.rug : ''), c.verdict.age + ' old') : kv('VERDICT', 'not run yet'));
+      if (c.larp) {
+        b.body.appendChild(kv('LARP', c.larp.flags + ' evidence flag' + (c.larp.flags === 1 ? '' : 's') + ' (evidence, not a verdict)', c.larp.age + ' old'));
+        c.larp.items.slice(0, 3).forEach(function(i){ b.body.appendChild(el('div', 'small', '  \\u00b7 ' + i)); });
+      } else b.body.appendChild(kv('LARP', 'not checked yet'));
+      if (c.holders) {
+        b.body.appendChild(kv('HOLDERS', c.holders.text, c.holders.age + ' old'));
+        var bar = el('div', 'bar'); var f = el('div', 'fill'); f.style.width = Math.max(0, Math.min(100, c.holders.top10Pct)) + '%'; bar.appendChild(f); b.body.appendChild(bar);
+        b.body.appendChild(el('div', 'small', c.holders.basis));
+      } else b.body.appendChild(kv('HOLDERS', 'not read yet'));
+      if (c.flags.length) {
+        b.body.appendChild(el('div', 'k', 'LIVE SIGNALS'));
+        c.flags.forEach(function(s){ b.body.appendChild(el('div', 'flag ' + s.level, '\\u25cf ' + s.title + ' \\u00b7 ' + s.text + ' \\u00b7 ' + s.source + ' \\u00b7 ' + s.age + ' old' + (s.stale ? ' (stale)' : ''))); });
+      } else b.body.appendChild(kv('SIGNALS', 'none fired yet'));
+    },
+    pnl: function(b, v){
+      clear(b.body);
+      b.stamp.hidden = !v.stamp;
+      if (v.stamp) { b.stamp.textContent = v.strip || (v.stamp === 'LIVE' ? 'LIVE' : 'PAPER \\u00b7 SIMULATED'); b.stamp.className = 'chip ' + (v.stamp === 'LIVE' ? 'live' : 'paper'); }
+      if (!v.png) { b.body.appendChild(el('div', 'empty', v.note)); return; }
+      var card = el('div', 'card');
+      var img = new Image(v.w, v.h); img.alt = (v.stamp || '') + ' PnL card'; img.src = 'data:image/png;base64,' + v.png;
+      card.appendChild(img);
+      if (v.sample) card.appendChild(el('div', 'banner', 'SAMPLE DATA \\u00b7 REPLAY OF A SAVED SESSION'));
+      b.body.appendChild(card);
+      b.body.appendChild(el('div', 'small', v.note));
+    }
+  };
+  var ws = new WebSocket(WS_URL);
+  ws.onmessage = function(m){
+    var msg; try { msg = JSON.parse(m.data); } catch (e) { return; }
+    if (!msg || msg.type !== 'view' || !boxes[msg.scene] || !render[msg.scene]) return;
+    var b = boxes[msg.scene];
+    header(b, msg.view);
+    render[msg.scene](b, msg.view);
+  };
+  ws.onclose = function(){ SCENES.forEach(function(s){ boxes[s].conn.hidden = false; boxes[s].conn.textContent = 'disconnected \\u00b7 run dexterm overlay for a fresh URL'; }); };
+})();
+`;
+const htmlEscape = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/** The full document for one scene page (or 'all'). Values substituted here are ours (theme tokens, ws url). */
+export function renderOverlayPage(o) {
+    const t = OVERLAY_THEMES[o.theme];
+    const css = CSS.replace(/__([A-Z]+)__/g, (_m, k) => t[k.toLowerCase()] ?? '');
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8">`
+        + `<meta name="dexterm-page" content="${htmlEscape(o.page)}"><meta name="dexterm-ws" content="${htmlEscape(o.wsUrl)}">`
+        + `<title>dexterm overlay · ${htmlEscape(o.page)}</title><style nonce="${o.nonce}">${css}</style></head>`
+        + `<body><main id="root"></main><script nonce="${o.nonce}">${JS}</script></body></html>`;
+}

package/dist/packages/cli/src/overlay/pnl.js

@@ -0,0 +1,75 @@
+// dexterm — STREAMER OVERLAY PnL scene (task-1427). Draws the coin's result with the task-1407 card renderer, so
+// the stamp (PAPER / LIVE), the provenance block, the data ages and the "not financial advice" footer are the
+// renderer's own and cannot be turned off here.
+//
+// Two sources, never mixed:
+//   - the spectator stream (default): the agent's PAPER fills on the coin, exactly as the paper desk booked them.
+//     The stream only ever carries paper fills (an agent can never trade for real), so this card is always PAPER.
+//   - the trade ledger (`--ledger <tradeId>`): one round trip of the user's own unified ledger, read from the local
+//     file (no network). Its wallet mode picks the stamp: paper → PAPER, devnet / live → LIVE. A real-mode row is
+//     refused by the adapter (dexterm only modelled that fill).
+// Addresses are masked before they reach the card (the stream copy is already redacted; a ledger mint is masked
+// here), the size is a band, and the wallet is never drawn. A ledger row's tx signatures stay in the card input so
+// the LIVE note counts them truthfully; the renderer prints a signature only with showWallet, which the overlay
+// never sets, and only the PNG leaves this module.
+import { computeCard, cardPng, stampOf, CardError, CARD_GEOMETRY, ledgerCardInput } from "../pnl-card.js";
+import { maskAddress } from '../../../agents/src/index.js';
+import { THEMES } from '../../../tui/src/index.js';
+import { fmtAgeShort } from "./model.js";
+/** Paper fills carry whole-token amounts; the card's integer token maths uses this many decimals for them. */
+const STREAM_DECIMALS = 6;
+/** Card input from the stream's PAPER fills on one coin. The mark (open position) is the newest stream price. */
+export function streamCardInput(state, mint) {
+    const p = state.paper.get(mint);
+    if (!p || !p.fills.length)
+        return null;
+    const scale = 10 ** STREAM_DECIMALS;
+    const fills = p.fills.map((f) => ({
+        t: f.t, side: f.side, solDelta: (f.side === 'buy' ? -1 : 1) * Math.abs(f.sol),
+        tokenDelta: BigInt(Math.round(f.qty * scale)) * (f.side === 'buy' ? 1n : -1n), feeSol: null, sig: null,
+    }));
+    // Mark: the newest price the stream carried, in SOL via the SOL/USD rate the newest priced fill implies
+    // (its USD price ÷ its SOL price). Without a later price, the last fill's own SOL price marks the position.
+    const last = p.fills[p.fills.length - 1];
+    const lastSolPx = Math.abs(last.sol) / last.qty;
+    const priced = [...p.fills].reverse().find((f) => f.priceUsd !== null && f.priceUsd > 0);
+    const c = state.coins.get(mint);
+    let mark = { priceSol: lastSolPx, at: last.t, via: 'last paper fill' };
+    if (priced && c?.priceUsd && c.priceUsd.at > last.t) {
+        const solUsd = priced.priceUsd / (Math.abs(priced.sol) / priced.qty);
+        if (solUsd > 0 && Number.isFinite(solUsd))
+            mark = { priceSol: c.priceUsd.value / solUsd, at: c.priceUsd.at - c.priceUsd.ageSec * 1000, via: 'stream price, SOL/USD implied by the paper fill' };
+    }
+    return {
+        source: 'paper', mint, symbol: p.symbol, name: null, decimals: STREAM_DECIMALS, fills,
+        ledger: 'agent paper desk via the spectator stream', wallet: null, mark,
+        excluded: [], fees: 'as booked by the paper desk (simulated)', image: null, supply: null,
+    };
+}
+/** Card input from one ledger row, the mint masked first (the overlay never shows a full address). */
+export function ledgerOverlayInput(row, solUsd) {
+    const input = ledgerCardInput(row, { solUsd });
+    return { ...input, mint: maskAddress(row.mint) };
+}
+function header(state, s, now) {
+    const ageSec = s ? Math.max(0, now - (s.open && s.input.mark ? s.input.mark.at : s.lastT)) / 1000 : null;
+    return { sample: state.sample, ageSec, age: ageSec === null ? 'no data yet' : `data age ${fmtAgeShort(ageSec)}` };
+}
+/** Render the PnL scene. `input` null → the stream's current coin. Never throws: a refusal becomes the note. */
+export function pnlView(state, now, input) {
+    const g = CARD_GEOMETRY.wide;
+    const inp = input ?? (state.paperCurrent ? streamCardInput(state, state.paperCurrent) : null);
+    if (!inp)
+        return { scene: 'pnl', ...header(state, null, now), stamp: null, strip: null, png: null, w: g.w, h: g.h, note: 'no PAPER trade by the agent yet' };
+    let s;
+    try {
+        s = computeCard(inp, now);
+    }
+    catch (e) {
+        if (e instanceof CardError)
+            return { scene: 'pnl', ...header(state, null, now), stamp: null, strip: null, png: null, w: g.w, h: g.h, note: e.message };
+        throw e;
+    }
+    const png = cardPng(s, { aspect: 'wide' }).toString('base64');
+    return { scene: 'pnl', ...header(state, s, now), stamp: inp.source === 'paper' ? 'PAPER' : 'LIVE', strip: stampOf(s, THEMES.cyberspace).strip, png, w: g.w, h: g.h, note: inp.ledger };
+}