dexterm-cli 0.1.2 → 0.1.3

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

@@ -15,8 +15,11 @@
 // Helius key (keyless prints the fix) and reads public history. Secrets never print: the RPC URL stays inside the
 // data layer.
 import { createDataLayer, resolveRpcUrl, HeliusHistory } from '../../data/src/index.js';
-import { FollowStore, WalletTracker, defaultFollowsPath, isWalletAddress, shortAddr, CopyAuto, defaultCopyJournalPath, AUTO_HARD, autoSizeCap } from '../../data/src/trade/copy/index.js';
+import { FollowStore, WalletTracker, defaultFollowsPath, isWalletAddress, shortAddr, fmtHoldMs, CopyAuto, defaultCopyJournalPath, AUTO_HARD, autoSizeCap, buildMirror, leaderSoldSince } from '../../data/src/trade/copy/index.js';
 import { PlanService, defaultPlansJournalPath } from '../../data/src/trade/plans/index.js';
+import { CopyLive } from "./live/copy.js";
+/** Default per-mirror cap for the headless path (same as the TUI's MIRROR_DEFAULT_CAP_USD); overridable with --cap. */
+export const FOLLOW_MIRROR_DEFAULT_CAP_USD = 20;
 function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
 function has(rest, name) { return rest.includes(name); }
 const USAGE = `dexterm follow <command>
@@ -25,6 +28,9 @@ const USAGE = `dexterm follow <command>
   list [--json]
   stats <addr> [--json]            one Helius history fetch: trades, FIFO realised PnL, win rate (hidden under n=10)
   trades <addr> [--limit N]        the decoded swaps behind the stats
+  mirror <addr> [--cap USD] [--k X] [--propose] [--json]
+                                   preview a MIRROR TICKET from this wallet's latest BUY (checks + size);
+                                   --propose writes it as an INERT order plan (arm only in the app, keypress/Phantom gate)
   purge --yes                      delete every follow and label
   auto <addr> [--per-trade USD] [--daily USD] [--max-open N] [--cooldown SEC] [--k X] [--disarm N] [--off]
                                    draft the auto-mirror caps (always OFF here: enabling is a keypress in the app, U then A,
@@ -35,7 +41,9 @@ function fmtStats(s) {
         `${shortAddr(s.wallet)}  ${s.trades} trades (${s.buys} buys · ${s.sells} sells · ${s.transfers} transfers) over ${s.mints} mints · ${s.sample.note}`,
         `realised ${s.realisedSol >= 0 ? '+' : ''}${s.realisedSol.toFixed(4)} SOL${s.realisedUsd !== null ? ` (${s.realisedUsd >= 0 ? '+' : ''}$${s.realisedUsd.toFixed(2)} at $${s.solUsdAt}/SOL now)` : ' (no SOL price: USD not shown)'} · FIFO over fetched history, fees and tips included`,
         `win rate ${s.winRate === null ? '—' : `${(s.winRate * 100).toFixed(0)}%`} · ${s.winRateNote} · open positions ${s.open}`,
+        `hold time ${fmtHoldMs(s.holdMedianMs)} · ${s.holdNote}`,
         `early-entry score ${s.earlyEntry.score === null ? '—' : s.earlyEntry.score.toFixed(2)} · ${s.earlyEntry.note}`,
+        `source ${s.sample.source}${s.sample.asOf ? ` · as of ${new Date(s.sample.asOf).toISOString().replace('T', ' ').slice(0, 19)} (${Math.max(0, Math.round((Date.now() - s.sample.asOf) / 1000))}s ago)` : ' · not fetched yet'}`,
     ];
     for (const p of s.positions.slice(0, 12))
         out.push(`  ${shortAddr(p.mint)}  ${p.closed ? 'closed' : 'open  '}  realised ${p.realisedSol >= 0 ? '+' : ''}${p.realisedSol.toFixed(4)} SOL  ${p.buys}b/${p.sells}s${p.flagged ? '  (cost-0 lot: airdrop/transfer/unpriced leg)' : ''}`);
@@ -209,6 +217,104 @@ export async function runFollow(rest, io, over = {}) {
                 dl?.close();
             }
         }
+        // task-1400 Tier 2 (headless): the one-key MIRROR TICKET from a shell. Reuses the exact TUI path — poll the
+        // tracker, take the wallet's latest BUY alert, resolve its market, run buildMirror. --propose writes the result
+        // as an INERT `proposed` order plan through PlanService; it is armable ONLY through the app's keypress / Phantom
+        // gate. There is no arm/sign/execute path in this command (the plan engine refuses to arm without a gesture and
+        // an armed mandate), so a pipe or an agent calling `follow mirror --propose` can never trade.
+        case 'mirror': {
+            const addr = rest[1];
+            if (!isWalletAddress(addr)) {
+                errOut('usage: dexterm follow mirror <addr> [--cap USD] [--k X] [--propose] [--json]');
+                return 2;
+            }
+            if (!store.has(addr)) {
+                errOut(`dexterm follow mirror: ${shortAddr(addr)} is not followed (dexterm follow add <addr> first)`);
+                return 1;
+            }
+            const capUsd = flag(rest, '--cap') ? Number(flag(rest, '--cap')) : FOLLOW_MIRROR_DEFAULT_CAP_USD;
+            if (!(capUsd > 0)) {
+                errOut('dexterm follow mirror: --cap needs a USD number > 0');
+                return 2;
+            }
+            const kRaw = flag(rest, '--k');
+            const k = kRaw ? Number(kRaw) : undefined;
+            if (kRaw !== undefined && !(k > 0)) {
+                errOut('dexterm follow mirror: --k needs a number > 0');
+                return 2;
+            }
+            let dl = null;
+            let history;
+            if (over.history !== undefined)
+                history = over.history;
+            else {
+                const rpc = resolveRpcUrl({ env: io.env });
+                if (rpc.provider !== 'helius')
+                    history = null;
+                else {
+                    dl = createDataLayer({ rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
+                    history = dl.rpcPool.heliusUrl ? new HeliusHistory(dl.http, dl.rpcPool.heliusUrl) : null;
+                }
+            }
+            try {
+                const copy = new CopyLive(dl, { followsPath: null, history, solUsd: () => over.solUsd ?? null, ...(over.clock ? { clock: over.clock } : {}) });
+                copy.store.add(addr);
+                if (copy.status().state === 'unavailable') {
+                    errOut(`dexterm follow mirror: ${copy.status().why}`);
+                    return 1;
+                }
+                await copy.tracker.pollOnce();
+                const after = copy.status();
+                if (after.state === 'degraded') {
+                    errOut(`dexterm follow mirror: ${after.why}`);
+                    return 1;
+                }
+                // Prefer a live "news" buy alert (a buy the tracker saw AFTER priming). A one-shot shell call primes and
+                // sees the history in a single poll, so there is usually no news alert yet; fall back to the latest BUY in
+                // the fetched history, synthesising the same CopyAlert shape and captioning it as history, not live news.
+                let alert = copy.alerts(200).find((a) => a.wallet === addr && a.trade.side === 'buy');
+                let fromHistory = false;
+                if (!alert) {
+                    const lastBuy = copy.trades(addr).filter((t) => t.side === 'buy').sort((a, b) => b.slot - a.slot || b.sig.localeCompare(a.sig))[0];
+                    if (!lastBuy) {
+                        out(`no BUY from ${shortAddr(addr)} in the fetched history (nothing to mirror)`);
+                        return 0;
+                    }
+                    alert = { id: `copy_hist_${lastBuy.sig.slice(0, 12)}`, t: copy.now(), wallet: addr, name: store.get(addr)?.name ?? null, trade: lastBuy, lagMs: lastBuy.tKnown ? Math.max(0, copy.now() - lastBuy.t) : null };
+                    fromHistory = true;
+                }
+                const market = over.mirrorMarket ? await over.mirrorMarket(alert.trade.mint) : await copy.mirrorMarket(alert.trade.mint);
+                const soldSince = leaderSoldSince(alert, copy.trades(addr));
+                // No wallet-intel scan from a shell: the leader's dev-cluster / holdings stay unknown (shown as such).
+                const result = buildMirror(alert, { now: copy.now(), capUsd, k, market, leaderSoldSince: soldSince, leaderIntel: null });
+                if (has(rest, '--json')) {
+                    out(JSON.stringify(result));
+                    return result.ok ? 0 : 1;
+                }
+                out(`mirror of ${shortAddr(addr)}'s latest BUY — ${shortAddr(alert.trade.mint)}${market.symbol ? ` (${market.symbol})` : ''}${fromHistory ? ' · from fetched history (not a live alert)' : ' · live alert'}`);
+                for (const c of result.checks)
+                    out(`  ${c.ok === true ? 'ok ' : c.ok === false ? 'NO ' : '?  '} ${c.name.padEnd(12)} ${c.detail}`);
+                if (!result.ok) {
+                    errOut(`refused: ${result.reason} — ${result.message}`);
+                    return 1;
+                }
+                out(`  size $${result.sizeUsd.toFixed(2)} = ${result.sizeWhy}`);
+                if (!has(rest, '--propose')) {
+                    out('preview only · add --propose to write the inert plan (then arm it in the app: O screen, hold a — keypress/Phantom gate)');
+                    out('not a recommendation · a wallet\'s past fills say nothing about its next one');
+                    return 0;
+                }
+                const plans = new PlanService({ journalPath: over.plansJournalPath === undefined ? defaultPlansJournalPath(io.env) : over.plansJournalPath });
+                const plan = plans.propose(result.input, { supply: result.supply, by: 'copy', ref: result.ref });
+                out(`proposed ${plan.id} · ${plan.status.toUpperCase()} (${plan.side} ${plan.symbol} ≈ $${plan.sizeUsd.toFixed(2)}) · INERT — nothing is armed`);
+                out('arm it in the app: U → O (the plans screen), select it, hold a (keypress) or approve in Phantom · the gate stays on');
+                out('not a recommendation · a wallet\'s past fills say nothing about its next one');
+                return 0;
+            }
+            finally {
+                dl?.close();
+            }
+        }
         default:
             if (cmd) {
                 errOut(`dexterm follow: unknown subcommand ${JSON.stringify(cmd)}`);

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

@@ -0,0 +1,48 @@
+// `dexterm help [topic]` (task-1413) — the app-help knowledge base from the command line, backed by the
+// same generated entries as the analyst's `app_help` MCP tool. No network, no model.
+//   dexterm help                 list the topics
+//   dexterm help export          show the best-matching topic (exact key/command + how-to)
+//   dexterm help screen token    multi-word query
+import { loadAppHelp, searchAppHelp, getAppHelp } from '../../mcp/src/index.js';
+function show(e, io) {
+    io.stdout.write(`\n${e.title}  (${e.id})\n`);
+    io.stdout.write(`${'─'.repeat(Math.min(60, e.title.length + e.id.length + 4))}\n`);
+    if (e.keys.length)
+        io.stdout.write(`Keys:     ${e.keys.join('  ')}\n`);
+    if (e.commands.length)
+        io.stdout.write(`Commands: ${e.commands.map((c) => `dexterm ${c}`).join('  ')}\n`);
+    if (e.flags.length)
+        io.stdout.write(`Flags:    ${e.flags.join('  ')}\n`);
+    io.stdout.write(`\n${e.body}\n`);
+}
+export function helpCommand(argv, io) {
+    const entries = loadAppHelp();
+    if (!entries.length) {
+        io.stderr.write('no app-help entries found\n');
+        return 1;
+    }
+    const query = argv.join(' ').trim();
+    if (!query) {
+        io.stdout.write('dexterm help <topic> — how the app works. Topics:\n\n');
+        for (const e of entries)
+            io.stdout.write(`  ${e.id.padEnd(26)} ${e.title}\n`);
+        io.stdout.write('\nExamples: dexterm help export · dexterm help voice speed · dexterm help screener\n');
+        return 0;
+    }
+    // Exact id wins; otherwise the best retrieval match, with near-misses listed.
+    const exact = getAppHelp(query.replace(/\s+/g, '-'), entries) ?? getAppHelp(query, entries);
+    if (exact) {
+        show(exact, io);
+        return 0;
+    }
+    const results = searchAppHelp(query, 5, entries);
+    if (!results.length) {
+        io.stdout.write(`No app-help topic matches "${query}". Run \`dexterm help\` to list topics.\n`);
+        return 1;
+    }
+    show(results[0], io);
+    if (results.length > 1) {
+        io.stdout.write(`\nRelated: ${results.slice(1).map((r) => r.id).join(', ')}\n`);
+    }
+    return 0;
+}

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

@@ -10,15 +10,24 @@ import { NewPairsLive } from "./newpairs.js";
 import { WatchlistLive } from "./watchlist.js";
 import { TradeTicketLive, PositionsLive, LivePositions, CombinedPositions, POSITIONS_REFRESH_MS } from "./trade.js";
 import { IntelLive } from "./intel.js";
+import { LiveSignalsLive } from "./signals.js";
 import { CopyLive } from "./copy.js";
 export { TokenLive, INTERVALS, panelCaption, emptyView } from "./token.js";
 export { NewPairsLive, latencyStats, percentile, RECENT_POLL_MS, NEW_TOKENS_POLL_MS, ENRICH_POLL_MS } from "./newpairs.js";
 export { WatchlistLive, WATCH_REFRESH_MS } from "./watchlist.js";
 export { TradeTicketLive, PositionsLive, LivePositions, CombinedPositions, POSITIONS_REFRESH_MS } from "./trade.js";
 export { IntelLive, popupBubbleVM, unavailableText, INTEL_AUTOSCAN_DELAY_MS } from "./intel.js";
+export { LiveSignalsLive, buildObservation, SIGNALS_LOG_MAX } from "./signals.js";
 export { renderTokenLive } from "./screens/token-live.js";
 export { renderNewPairsLive } from "./screens/newpairs-live.js";
 export { renderWatchlistLive } from "./screens/watchlist-live.js";
+/** task-1404: how often the open token's credit-metered wallet-intel leg (holders/bundle/sniper/fresh) is re-scanned. */
+export const INTEL_RESCAN_MS = 45_000;
+/** A transient one-liner for a fired live signal (⚑ SYMBOL-less; the token screen shows the full strip). */
+function signalNotice(s) {
+    const age = s.dataAgeMs >= 1000 ? ` · ${Math.round(s.dataAgeMs / 1000)}s` : '';
+    return `⚑ ${s.title}: ${s.text} (${s.source}${age})`;
+}
 export class LiveContext {
     dl;
     mode;
@@ -54,6 +63,8 @@ export class LiveContext {
     token = null;
     /** task-1340 wallet intel: the holder scan per mint (light on open, deep for watched coins) behind the bubble map. */
     intel;
+    /** task-1404 LIVE holder/rug signals: turns the open token's repeated holder/safety reads into signal events. */
+    signals;
     /** task-1360 copy trading Tier 1: the follow store + wallet tracker (alerts on a followed wallet's buys/sells). */
     copy;
     /**
@@ -86,6 +97,8 @@ export class LiveContext {
     onLog;
     lastFastLogAt = 0;
     lastFastLog = '';
+    /** task-1404: last time the open token's wallet-intel leg was re-scanned (slow cadence; see refreshOpenIntel). */
+    lastIntelRescanAt = 0;
     constructor(dl, opts) {
         this.dl = dl;
         this.mode = opts.mode;
@@ -124,7 +137,7 @@ export class LiveContext {
                 endpoints: opts.fastEndpoints,
                 solUsd: () => this.solUsd,
                 ws: opts.ws,
-                onPrice: (_p) => emit('fastprice'),
+                onPrice: (_p) => { this.observeSignals(); emit('fastprice'); },
                 onStatus: () => { emit('fastlane:status'); this.logFast(); },
             })
             : null;
@@ -166,7 +179,10 @@ export class LiveContext {
             ? new LivePositions(this.trade.paths?.liveLedger ?? defaultLiveLedgerPath(), { now: this.now, mark: (m) => this.positions.markOf(m), solUsd: () => this.positions.solUsd() ?? this.solUsd })
             : null;
         this.positionSource = new CombinedPositions(this.positions, this.livePositions);
-        this.intel = new IntelLive(dl, { now: this.now, onChange: () => { this.syncIntelRows(); emit('intel'); }, isWatched: (mint) => this.watch.has(mint) });
+        this.intel = new IntelLive(dl, { now: this.now, onChange: () => { this.syncIntelRows(); this.observeSignals(); emit('intel'); }, isWatched: (mint) => this.watch.has(mint) });
+        // task-1404: the live holder/rug signals engine. A fired signal sets a transient notice and redraws; the
+        // token screen shows the recent signals, and the rules engine reads `signals.fields()` so each is an alert trigger.
+        this.signals = new LiveSignalsLive({ now: this.now, onSignal: (s) => { this.notice = signalNotice(s); emit('signals'); } });
         // task-1360: followed wallets are polled only in a real live run (replay never spends credits); the store is always readable.
         this.copy = new CopyLive(opts.mode === 'live' ? dl : null, { onChange: (r) => emit(r), solUsd: () => this.solUsd, env: opts.copy?.env, followsPath: opts.copy?.followsPath, history: opts.copy?.history, pollMs: opts.copy?.pollMs });
     }
@@ -376,7 +392,7 @@ export class LiveContext {
     }
     /** Open a token: a fresh loader, first load kicked off; the view is readable immediately (row fields). */
     openToken(row) {
-        const t = new TokenLive(this.dl, row, { interval: this.token?.view.interval ?? this.interval, now: this.now, onChange: () => { this.syncChainRows(t); this.onChange('token'); } });
+        const t = new TokenLive(this.dl, row, { interval: this.token?.view.interval ?? this.interval, now: this.now, onChange: () => { this.syncChainRows(t); this.observeSignals(); this.onChange('token'); } });
         this.token = t;
         this.syncFastSet(); // promote the opened token to the fast lane (slow→fast, no seam)
         this.x?.setFocus({ mint: row.mint, symbol: row.symbol }); // task-1357: the open token's X search (60 s, cached 15 min)
@@ -423,6 +439,51 @@ export class LiveContext {
         if (sigs.length)
             this.social.ingest(sigs.map((s) => chainSignalToRaw(s, this.now())));
     }
+    /** The current inputs for the live-signals engine: the open token's view + its settled intel scan + fast-lane curve. */
+    signalInputs() {
+        if (!this.token)
+            return null;
+        const mint = this.token.view.mint;
+        const result = this.intel.entry(mint)?.result;
+        const ok = result && result.state === 'ok' ? result : null;
+        return {
+            view: this.token.view,
+            intel: ok ? { analysis: ok.analysis, fetchedAt: ok.fetchedAt, via: ok.via.history ? 'helius' : ok.via.holders } : null,
+            curve: this.fastLane?.curve(mint) ?? null,
+        };
+    }
+    /**
+     * task-1404: feed one moment of the open token's holder/rug state to the live-signals engine. Called whenever the
+     * token, the intel scan or a fast-lane push changed something; the engine only emits on a real threshold-crossing
+     * change, so this is cheap to call on every redraw. Nothing fires until a second observation of the same field.
+     */
+    observeSignals() {
+        if (this.closed)
+            return;
+        const inputs = this.signalInputs();
+        if (inputs)
+            this.signals.observe(inputs);
+    }
+    /**
+     * task-1404: re-run the open token's wallet-intel scan on a slow cadence so holder/concentration/bundle/sniper
+     * signals stay LIVE, not computed once on open. Gated: live mode, the history leg can actually run (else a scan
+     * would only spend public-RPC calls to still print a dash), not already in flight, and at most once per
+     * INTEL_RESCAN_MS. The cheap on-chain reads (authorities, LP, liq, price) already refresh with token.load()
+     * every 10 s and bonding streams sub-second; this covers the credit-metered Helius leg.
+     */
+    refreshOpenIntel(now) {
+        if (this.mode !== 'live' || !this.token)
+            return;
+        if (now - this.lastIntelRescanAt < INTEL_RESCAN_MS)
+            return;
+        if (!this.intel.historyAvailable().ok)
+            return;
+        const v = this.token.view;
+        if (this.intel.entry(v.mint)?.state === 'loading')
+            return;
+        this.lastIntelRescanAt = now;
+        void this.intel.scan({ mint: v.mint, symbol: v.symbol, name: v.name, holderCount: v.holders ?? null }, { force: true }).catch(() => { });
+    }
     /** The token screen's `1`..`6` keys. */
     setTimeframe(n) {
         const iv = INTERVALS[n - 1];

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

@@ -214,6 +214,30 @@ export function renderTokenLive(c, state, v) {
                 sy += 1;
             }
         }
+        // task-1404: LIVE holder/rug signals — the changes seen since the token was opened (dev sell, concentration
+        // shift, LP unlock, authority flip, new bundle/sniper, fresh inflow, bonding, migration). Each is a risk flag,
+        // not a verdict, and carries its SOURCE and the AGE of the data it read; the `stale` mark shows honestly.
+        const sigs = state.live?.signals?.recent(v.mint, 4) ?? [];
+        if (sigs.length && sy < sb.y + sb.h) {
+            sy += sy + 1 < sb.y + sb.h ? 1 : 0;
+            if (sy < sb.y + sb.h) {
+                c.text(sb.x + 1, sy, 'LIVE SIGNALS', { fg: t.dim, bg: sb.bg });
+                sy += 1;
+            }
+            const staleAfter = 60_000;
+            for (const s of sigs) {
+                if (sy >= sb.y + sb.h)
+                    break;
+                const color = s.level === 'warn' ? t.warn : s.level === 'down' ? t.down : s.level === 'up' ? t.up : t.muted;
+                const ageMs = Math.max(0, now - s.at);
+                const stale = ageMs > staleAfter;
+                const meta = `${s.source} · ${ageMs >= 1000 ? `${Math.round(ageMs / 1000)}s` : 'now'}${stale ? ' · stale' : ''}`;
+                const metaClip = clip(meta, Math.max(8, Math.floor((sb.w - 2) / 2)));
+                c.text(sb.x + 1, sy, `⚑ ${s.title}`, { fg: color, bg: sb.bg, b: s.level === 'warn' || s.level === 'down' }, sb.w - 2 - metaClip.length - 1);
+                c.textR(sb.x + 1, sy, sb.w - 2, metaClip, { fg: stale ? t.warn : t.dim, bg: sb.bg, i: true });
+                sy += 1;
+            }
+        }
         if (bp !== 'compact') {
             const hx = statsW;
             const hw = mainW - statsW;

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

@@ -0,0 +1,109 @@
+// dexterm — LIVE holder/rug SIGNALS binding (task-1404). Turns the open token's repeatedly-refreshed holder and
+// safety reads (market/authorities/rugcheck panels + the wallet-intel scan + the fast-lane bonding curve) into
+// SIGNAL events through the pure @dexterm/data LiveSignalsEngine, keeps a small per-mint log for the token screen,
+// and exposes the latest numeric values as RULE FIELDS so every signal is an alert trigger (task-1398 pattern).
+//
+// It owns no timers and does no I/O: the UI loop / LiveContext calls observe() whenever the token, the intel scan
+// or a fast-lane push changed something. The engine dedups (only a threshold-crossing change emits), so calling it
+// on every redraw is cheap. Read-only: nothing here trades or signs.
+import { LiveSignalsEngine, bondingProgress, } from '../../../data/src/index.js';
+/** Max signals kept per mint for the token-screen strip (newest first). */
+export const SIGNALS_LOG_MAX = 40;
+function fromPanel(p, value, fallbackSource) {
+    if (!p || value == null || !Number.isFinite(value) || p.fetchedAt == null)
+        return null;
+    return { value, source: p.via ?? fallbackSource, fetchedAt: p.fetchedAt, stale: p.stale || p.state === 'error' };
+}
+function authFromPanel(p, present) {
+    if (!p || present == null || p.fetchedAt == null)
+        return null;
+    return { present, source: p.via ?? 'authorities', fetchedAt: p.fetchedAt, stale: p.stale || p.state === 'error' };
+}
+function fromIntel(value, intel) {
+    if (value == null || !Number.isFinite(value) || !intel || intel.fetchedAt == null)
+        return null;
+    return { value, source: intel.via ?? 'helius', fetchedAt: intel.fetchedAt, stale: false };
+}
+/**
+ * Build one observation from the token view + intel scan + fast-lane curve. Each field keeps its OWN source and
+ * fetch time so a signal is honest about where it came from and how old the data is. The richer wallet-intel
+ * figures (ex-pool top-10, creator %, bundled, snipers, fresh, cluster) are preferred when the scan has landed;
+ * otherwise the panel reads (Jupiter audit top-10/dev) stand in. Pure + exported for the tests.
+ */
+export function buildObservation(inputs, now) {
+    const v = inputs.view;
+    const I = inputs.intel?.analysis?.insights ?? null;
+    const panels = v.panels ?? {};
+    const obs = { mint: v.mint, at: now };
+    // top-10 concentration (pools excluded): the scan's ex-pool figure first, else the holders panel's top-10.
+    obs.top10 = (I && typeof I.top10.exPool === 'number' ? fromIntel(I.top10.exPool, inputs.intel) : null) ?? fromPanel(panels.holders, v.top10, 'holders');
+    // creator / dev share: the scan's creatorPctNow first, else the market panel's Jupiter audit devPct.
+    obs.dev = (I ? fromIntel(I.dev.creatorPctNow, inputs.intel) : null) ?? fromPanel(panels.market, v.dev, 'jupiter');
+    // bundled / snipers / fresh / cluster only exist once the launch window / funders were read (Helius).
+    if (I && I.coverage.launchTxs > 0) {
+        obs.bundled = fromIntel(I.bundle.bundlePctOfTopSample, inputs.intel);
+        obs.snipers = fromIntel(I.snipers.count, inputs.intel);
+    }
+    if (I && I.coverage.fundingLookups > 0)
+        obs.fresh = fromIntel(I.fresh.freshAtBuyPctOfTopSample, inputs.intel);
+    const cluster = inputs.intel?.analysis?.clusters?.[0]?.pct ?? null;
+    obs.cluster = fromIntel(cluster, inputs.intel);
+    // LP locked (RugCheck), liquidity (market), mint/freeze authority (authorities panel).
+    obs.lpLocked = fromPanel(panels.rugcheck, v.lpLocked, 'rugcheck');
+    obs.liq = fromPanel(panels.market, v.liq, 'market');
+    obs.mintAuth = authFromPanel(panels.authorities, v.mintAuth);
+    obs.freezeAuth = authFromPanel(panels.authorities, v.freezeAuth);
+    // bonding-curve progress + migration from the on-chain fast-lane push (sub-second), when streaming.
+    if (inputs.curve) {
+        const bp = bondingProgress(inputs.curve.curve.vToken);
+        if (bp != null)
+            obs.bonding = { value: bp, source: 'onchain-curve', fetchedAt: inputs.curve.at, stale: false };
+        obs.migrated = { value: inputs.curve.curve.complete, source: 'onchain-curve', fetchedAt: inputs.curve.at, stale: false };
+    }
+    return obs;
+}
+export class LiveSignalsLive {
+    engine;
+    now;
+    onSignal;
+    logByMint = new Map();
+    /** Signals emitted this session (all mints), newest last — a cheap counter/feed for the smoke script + tests. */
+    emitted = [];
+    constructor(opts = {}) {
+        this.engine = new LiveSignalsEngine({ thresholds: opts.thresholds });
+        this.now = opts.now ?? (() => Date.now());
+        this.onSignal = opts.onSignal;
+    }
+    /** Observe one moment of a token's state; records and returns any new signals. */
+    observe(inputs) {
+        const obs = buildObservation(inputs, this.now());
+        const sigs = this.engine.observe(obs);
+        for (const s of sigs) {
+            const arr = this.logByMint.get(s.mint) ?? [];
+            arr.unshift(s);
+            if (arr.length > SIGNALS_LOG_MAX)
+                arr.length = SIGNALS_LOG_MAX;
+            this.logByMint.set(s.mint, arr);
+            this.emitted.push(s);
+            this.onSignal?.(s);
+        }
+        return sigs;
+    }
+    /** Recent signals for a mint, newest first (token-screen LIVE SIGNALS strip). */
+    recent(mint, limit = 8) {
+        return (this.logByMint.get(mint) ?? []).slice(0, limit);
+    }
+    /** Latest numeric fields for the rules engine (merged into the open-token RuleRow in ruleRowsOf). */
+    fields(mint) {
+        return this.engine.fields(mint);
+    }
+    /** Per-field snapshot (value + source + age + stale) for the strip header. */
+    snapshot(mint, now = this.now()) {
+        return this.engine.snapshot(mint, now);
+    }
+    /** Drop a mint the UI no longer tracks. */
+    forget(mint) {
+        this.engine.forget(mint);
+        this.logByMint.delete(mint);
+    }
+}

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

@@ -680,6 +680,8 @@ export class PositionsLive {
     now;
     /** mint → current price in SOL per whole token. */
     marks = new Map();
+    /** task-1407: when each mark was taken (ms), so a PnL card can print the mark's age. */
+    markTimes = new Map();
     solPriceUsd = null;
     loading = false;
     heldMemo = new Map();
@@ -703,6 +705,10 @@ export class PositionsLive {
     markOf(mint) {
         return this.marks.get(mint) ?? null;
     }
+    /** task-1407: when the mark for a mint was taken (ms), or null when there is none. */
+    markAt(mint) {
+        return this.marks.has(mint) ? this.markTimes.get(mint) ?? null : null;
+    }
     /**
      * PositionSource: the open paper position for a mint, or null. One indexed SQLite read, reused for
      * HELD_MEMO_MS so a 30 fps render loop does not hit the ledger every frame. A closed wallet reads as flat.
@@ -758,8 +764,10 @@ export class PositionsLive {
                         continue;
                     }
                     const usd = byMint.get(m)?.pair.priceUsd ?? null;
-                    if (usd && usd > 0)
+                    if (usd && usd > 0) {
                         this.marks.set(m, usd / this.solPriceUsd);
+                        this.markTimes.set(m, this.now());
+                    }
                 }
             }
         }
@@ -865,6 +873,21 @@ export class LivePositions {
         this.rowsMemo = { at: now, rows };
         return rows;
     }
+    /** task-1407: the raw ledger rows (newest first, swaps only) with network + signature, for the LIVE PnL card. */
+    fills(mint, limit = 500) {
+        try {
+            const l = new LiveLedger({ path: this.path, readOnly: true });
+            try {
+                return l.trades(limit * 2).filter((r) => r.kind === 'swap' && r.mint === mint).slice(0, limit);
+            }
+            finally {
+                l.close();
+            }
+        }
+        catch {
+            return [];
+        }
+    }
     /** Confirmed live fills (newest first) for the popup markers / history; probes excluded. */
     records(limit = 100, mint) {
         try {