dexterm-cli 0.1.7 → 0.2.1

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

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

@@ -0,0 +1,170 @@
+// dexterm — STREAMER OVERLAY page server (task-1427). Serves the OBS browser-source scenes on loopback with the
+// popup host's security model (packages/popup/src/server.ts):
+//   * listens on 127.0.0.1 only (a random port unless --port), never 0.0.0.0 / ::; the remote must be loopback;
+//   * a scene URL carries a single-use TICKET (32 random bytes). OBS needs time to be pasted into, so its TTL is
+//     longer than a popup's (10 min by default) — but it still buys exactly one page load;
+//   * the page embeds a single-use WS TOKEN (30 s) accepted once for the WebSocket upgrade;
+//   * strict Host check on every request (DNS-rebind guard), strict Origin check on the upgrade; no CORS header is
+//     ever set; anything unknown or unauthorised gets an empty 404 and is reported as a probe;
+//   * the page's JS/CSS are inlined under a per-page nonce CSP: no remote content, no eval, no inline handlers;
+//     the only images are the PnL card PNG the socket delivers as a data: URL;
+//   * the socket is OUTBOUND ONLY: the server never parses what a page sends. Every inbound text frame is counted
+//     as dropped and ignored (pings are answered by the framing layer). There is no inbound control path: the
+//     server is constructed with nothing it could control, it only pushes view models it is handed.
+import http from 'node:http';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { WsConn } from '../../../agents/src/index.js';
+import { OVERLAY_SCENES } from "./model.js";
+import { renderOverlayPage, OVERLAY_THEMES } from "./page.js";
+export const OVERLAY_PAGES = [...OVERLAY_SCENES, 'all'];
+export const OVERLAY_TICKET_TTL_MS = 10 * 60_000;
+const WS_TOKEN_TTL_MS = 30_000;
+const LOOPBACK = new Set(['127.0.0.1', '::ffff:127.0.0.1', '::1']);
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+function safeEq(a, b) {
+    const ba = Buffer.from(a), bb = Buffer.from(b);
+    return ba.length === bb.length && timingSafeEqual(ba, bb);
+}
+const sanitize = (s, n = 80) => String(s ?? '').replace(/[^\x20-\x7e]/g, '?').slice(0, n);
+export async function createOverlayServer(opts = {}) {
+    const onEvent = opts.onEvent ?? (() => { });
+    const now = opts.now ?? (() => Date.now());
+    const ttl = Math.max(1000, opts.ticketTtlMs ?? OVERLAY_TICKET_TTL_MS);
+    const tickets = new Map();
+    const wsTokens = new Map();
+    const viewers = new Set();
+    const latest = new Map();
+    let dropped = 0;
+    let port = 0;
+    const probe = (req, reason) => onEvent({ ev: 'probe.rejected', reason, method: req.method ?? '', path: sanitize((req.url ?? '').replace(/([?&](p|t)=)[^&]*/g, '$1…')) });
+    const reject = (req, res, reason) => {
+        probe(req, reason);
+        res.writeHead(404, { 'content-length': '0', 'cache-control': 'no-store' });
+        res.end();
+    };
+    const baseChecks = (req) => {
+        if (!LOOPBACK.has(req.socket.remoteAddress ?? ''))
+            return 'remote-not-loopback';
+        if (req.headers.host !== `127.0.0.1:${port}`)
+            return 'bad-host';
+        return null;
+    };
+    const sweep = () => {
+        const t = now();
+        for (const [k, v] of tickets)
+            if (v.exp < t)
+                tickets.delete(k);
+        for (const [k, v] of wsTokens)
+            if (v.exp < t)
+                wsTokens.delete(k);
+    };
+    const server = http.createServer((req, res) => {
+        const bad = baseChecks(req);
+        if (bad)
+            return reject(req, res, bad);
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (req.method === 'GET' && url.pathname.startsWith('/overlay/')) {
+            sweep();
+            const page = url.pathname.slice('/overlay/'.length);
+            const p = url.searchParams.get('p') ?? '';
+            const key = [...tickets.keys()].find((k) => safeEq(k, p));
+            const t = key ? tickets.get(key) : undefined;
+            if (!key || !t || t.exp < now() || t.page !== page || !OVERLAY_PAGES.includes(page))
+                return reject(req, res, 'bad-ticket');
+            tickets.delete(key); // single use: a reload or a copied URL is refused
+            const wsToken = randomBytes(32).toString('base64url');
+            wsTokens.set(wsToken, { page, exp: now() + WS_TOKEN_TTL_MS });
+            const nonce = randomBytes(16).toString('base64url');
+            const html = renderOverlayPage({ page, theme: t.theme, nonce, wsUrl: `ws://127.0.0.1:${port}/ws?t=${wsToken}` });
+            res.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+                'x-content-type-options': 'nosniff',
+                'cross-origin-opener-policy': 'same-origin',
+                'cross-origin-resource-policy': 'same-origin',
+                'permissions-policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
+                'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src ws://127.0.0.1:${port}; img-src data:; font-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; object-src 'none'`,
+            });
+            onEvent({ ev: 'page.served', page });
+            return res.end(html);
+        }
+        return reject(req, res, 'unknown-route');
+    });
+    server.on('upgrade', (req, socket) => {
+        const fail = (reason) => {
+            probe(req, reason);
+            try {
+                socket.write('HTTP/1.1 404 Not Found\r\ncontent-length: 0\r\nconnection: close\r\n\r\n');
+            }
+            catch { /* gone */ }
+            socket.destroy();
+        };
+        const bad = baseChecks(req);
+        if (bad)
+            return fail(bad);
+        if (req.headers.origin !== `http://127.0.0.1:${port}`)
+            return fail('bad-origin');
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (url.pathname !== '/ws')
+            return fail('unknown-route');
+        sweep();
+        const tok = url.searchParams.get('t') ?? '';
+        const key = [...wsTokens.keys()].find((k) => safeEq(k, tok));
+        const entry = key ? wsTokens.get(key) : undefined;
+        if (!key || !entry || entry.exp < now())
+            return fail('bad-ws-token');
+        wsTokens.delete(key);
+        if (String(req.headers['sec-websocket-version']) !== '13' || !req.headers['sec-websocket-key'])
+            return fail('bad-ws-handshake');
+        const accept = createHash('sha1').update(req.headers['sec-websocket-key'] + WS_GUID).digest('base64');
+        socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+        const viewer = { page: entry.page, conn: new WsConn(socket, req.socket.remoteAddress ?? '') };
+        // Outbound only: whatever a page sends is never parsed, never forwarded, never acted on.
+        viewer.conn.onMessage = () => { dropped++; onEvent({ ev: 'viewer.dropped', page: viewer.page }); };
+        viewer.conn.onClose = () => { viewers.delete(viewer); onEvent({ ev: 'viewer.closed', page: viewer.page }); };
+        viewers.add(viewer);
+        onEvent({ ev: 'viewer.connected', page: viewer.page });
+        viewer.conn.send({ type: 'hello', protocol: 'dexterm-overlay/1', page: viewer.page });
+        for (const [scene, view] of latest)
+            if (viewer.page === 'all' || viewer.page === scene)
+                viewer.conn.send({ type: 'view', scene, view });
+    });
+    server.headersTimeout = 5000;
+    server.requestTimeout = 10_000;
+    server.keepAliveTimeout = 5000;
+    server.maxHeadersCount = 40;
+    await new Promise((resolve, rejectListen) => {
+        server.once('error', rejectListen);
+        server.listen(opts.port ?? 0, '127.0.0.1', () => { server.off('error', rejectListen); resolve(); });
+    });
+    port = server.address().port;
+    return {
+        port,
+        origin: `http://127.0.0.1:${port}`,
+        issueTicket(page, theme = 'cyberspace') {
+            if (!OVERLAY_PAGES.includes(page))
+                throw new Error(`unknown overlay scene ${JSON.stringify(page)} (one of ${OVERLAY_PAGES.join(', ')})`);
+            if (!(theme in OVERLAY_THEMES))
+                throw new Error(`unknown overlay theme ${JSON.stringify(theme)} (one of ${Object.keys(OVERLAY_THEMES).join(', ')})`);
+            sweep();
+            const ticket = randomBytes(32).toString('base64url');
+            tickets.set(ticket, { page, theme, exp: now() + ttl });
+            return `http://127.0.0.1:${port}/overlay/${page}?p=${ticket}`;
+        },
+        push(scene, view) {
+            latest.set(scene, view);
+            for (const v of viewers)
+                if (v.page === 'all' || v.page === scene)
+                    v.conn.send({ type: 'view', scene, view });
+        },
+        get viewers() { return viewers.size; },
+        get dropped() { return dropped; },
+        close() {
+            for (const v of [...viewers])
+                v.conn.close(1001);
+            viewers.clear();
+            return new Promise((r) => server.close(() => r()));
+        },
+    };
+}