dexterm-cli 0.1.2 → 0.1.4

package/dist/packages/cli/src/larp-detected.js

@@ -0,0 +1,209 @@
+// Local-only LARP/high-risk follow-up draft pipeline (task-1433). History mode reads the recorder
+// without network access, scores only the point-in-time t0 row, joins only later outcome labels, and
+// writes drafts/cards for human review. Live mode performs one read-only enrichment for one mint.
+// Nothing here has X credentials, opens a composer, schedules work, trades, arms, signs or posts.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createDataLayer, defaultDbPath } from '../../data/src/index.js';
+import { openHistoryReadOnly, exportRecorded } from '../../recorder/src/index.js';
+import { h1Model, rugFeaturesFromRecord, rugFeaturesFromToken } from '../../packs/src/index.js';
+import { Canvas, THEMES } from '../../tui/src/index.js';
+import { writeExport, fmtAge } from "./export.js";
+export const LARP_DRAFT_MIN_SAMPLE = 50;
+export const LARP_DRAFT_HORIZON = 259_200;
+export const LARP_DRAFT_THRESHOLD = 0.5;
+const isoMinute = (t) => new Date(t).toISOString().replace(/:\d\d\.\d{3}Z$/, 'Z');
+const shortMint = (mint) => `${mint.slice(0, 4)}...${mint.slice(-4)}`;
+const pct = (n, d) => `${d ? ((n / d) * 100).toFixed(1) : '0.0'}%`;
+/** One point-in-time flag per mint: earliest flagged t0 with an observed outcome at this horizon. */
+export function buildFollowUpDataset(records, horizonSec = LARP_DRAFT_HORIZON, threshold = LARP_DRAFT_THRESHOLD) {
+    const model = h1Model();
+    const byMint = new Map();
+    for (const r of records) {
+        const outcome = r.outcomes[`${horizonSec}`];
+        if (!outcome || byMint.has(r.mint))
+            continue;
+        const score = model.score(rugFeaturesFromRecord(r.features));
+        if (score < threshold)
+            continue;
+        byMint.set(r.mint, { mint: r.mint, t0: r.t0, score, model: model.id, outcome });
+    }
+    const flagged = [...byMint.values()];
+    const collapsed = flagged.filter((r) => r.outcome.positive);
+    return { horizonSec, threshold, flagged, collapsed, didNotCollapse: flagged.length - collapsed.length };
+}
+function outcomeText(o) {
+    if (o.label === 'rug')
+        return 'recorder label: liquidity-pull condition';
+    if (o.label === 'dead')
+        return 'recorder label: inactive at follow-up';
+    return `recorder label: ${o.label}`;
+}
+function datasetLine(d) {
+    return `Same-dataset follow-up: ${d.collapsed.length}/${d.flagged.length} met the condition (${pct(d.collapsed.length, d.flagged.length)}); ${d.didNotCollapse}/${d.flagged.length} did not.`;
+}
+function cardCanvas(row, d, now) {
+    const c = new Canvas(92, 25, THEMES.cyberspace);
+    const t = c.theme;
+    c.fill(0, 0, c.w, c.h, ' ', { bg: t.bg });
+    c.fill(0, 0, c.w, 3, ' ', { bg: t.headBg });
+    c.text(3, 1, 'LARP DETECTED · RECORDED FOLLOW-UP', { fg: t.warn, bg: t.headBg, b: true });
+    c.textR(0, 1, c.w - 3, shortMint(row.mint), { fg: t.muted, bg: t.headBg });
+    c.text(4, 5, 'AT THE RECORDED MOMENT', { fg: t.muted, b: true });
+    c.text(4, 7, `HIGH RISK ${Math.round(row.score * 100)}/100`, { fg: t.down, b: true });
+    c.text(4, 9, `${row.model} heuristic · model output · risk flag, not a certificate`, { fg: t.text });
+    c.text(4, 10, `${isoMinute(row.t0)} · local recorder · t0 evidence age ${fmtAge((now - row.t0) / 1000)}`, { fg: t.muted });
+    c.text(4, 13, 'LATER OBSERVED', { fg: t.muted, b: true });
+    c.text(4, 15, outcomeText(row.outcome).toUpperCase(), { fg: t.warn, b: true });
+    c.text(4, 17, `${fmtAge(d.horizonSec)} follow-up · ${row.outcome.tier} · labeler evidence`, { fg: t.text });
+    c.text(4, 20, datasetLine(d), { fg: t.muted }, c.w - 8);
+    c.text(4, 22, 'Sources: local dexterm recorder · DexScreener + Jupiter · draft only', { fg: t.muted }, c.w - 8);
+    c.text(4, 23, 'Not financial advice.', { fg: t.muted });
+    return c;
+}
+function historyDraft(row, d, now) {
+    return [
+        'LARP DETECTED — recorded follow-up',
+        '',
+        `Here is what the data showed: graded HIGH RISK ${Math.round(row.score * 100)}/100 at ${isoMinute(row.t0)} by ${row.model} (heuristic model output); ${outcomeText(row.outcome)} at the ${fmtAge(d.horizonSec)} follow-up.`,
+        '',
+        datasetLine(d),
+        '',
+        `Evidence: local dexterm recorder; DexScreener + Jupiter; t0 data age ${fmtAge((now - row.t0) / 1000)} at export; ${row.outcome.tier}; coin ${shortMint(row.mint)}.`,
+        '',
+        'A risk flag is not a certificate. Draft only; a human decides whether to post. Not financial advice.',
+    ].join('\n') + '\n';
+}
+export function renderHistoryDrafts(d, opts) {
+    const now = opts.now ?? Date.now();
+    const min = opts.minSample ?? LARP_DRAFT_MIN_SAMPLE;
+    if (d.flagged.length < min)
+        return { drafts: [], cards: [] };
+    mkdirSync(opts.outDir, { recursive: true, mode: 0o700 });
+    const rows = [...d.collapsed].sort((a, b) => b.t0 - a.t0).slice(0, opts.limit ?? 3);
+    const drafts = [], cards = [];
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const stem = `${String(i + 1).padStart(2, '0')}-${row.mint.slice(0, 4)}-${row.mint.slice(-4)}`;
+        const draft = join(opts.outDir, `${stem}.md`);
+        writeFileSync(draft, historyDraft(row, d, now), { mode: 0o600 });
+        drafts.push(draft);
+        const view = {
+            kind: 'larp-detected', title: `RECORDED FOLLOW-UP · ${shortMint(row.mint)}`, label: 'replay', canvas: cardCanvas(row, d, now),
+            ages: [
+                { name: 't0 evidence', source: 'local recorder · DexScreener + Jupiter', ageSec: (now - row.t0) / 1000 },
+                { name: 'follow-up', source: `${row.outcome.tier} recorder outcome`, ageSec: d.horizonSec },
+            ],
+            report: historyDraft(row, d, now).trimEnd().split('\n'),
+        };
+        const saved = writeExport(view, { dir: opts.outDir, now: now + i, subject: stem });
+        cards.push(saved.png);
+    }
+    return { drafts, cards };
+}
+function parse(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const value = argv[i + 1];
+        if (value !== undefined && !value.startsWith('--')) {
+            out[a.slice(2)] = value;
+            i++;
+        }
+        else
+            out[a.slice(2)] = true;
+    }
+    return out;
+}
+export const LARP_DETECTED_HELP = `dexterm larp-detected: local draft/card pipeline; never posts or schedules
+
+  dexterm larp-detected --out DIR [--db PATH] [--horizon SEC] [--limit 3]
+  dexterm larp-detected --live MINT --out DIR
+
+History mode is cron-ready and offline: it reads recorder t0 rows plus later labels, requires at least
+${LARP_DRAFT_MIN_SAMPLE} unique flagged coins, and otherwise writes no drafts. Live mode performs one read-only
+keyless lookup and writes a graded-now card. All output is for human review.`;
+function liveFeatures(row) {
+    return rugFeaturesFromToken({
+        liquidity_usd: row.pair.liquidityUsd, mcap: row.mcap?.value ?? row.pair.mcap, age_sec: row.token.createdAt === null ? null : Math.max(0, (Date.now() - row.token.createdAt) / 1000),
+        top10_pct: row.audit?.top10Pct ?? null, dev_pct: row.audit?.devPct ?? null, organic_score: row.stats?.organicScore ?? null,
+        holder_count: row.stats?.holderCount ?? null, mint_authority: row.audit?.mintAuthority ?? null, freeze_authority: row.audit?.freezeAuthority ?? null,
+    });
+}
+async function liveCard(mint, outDir, dbPath, io) {
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(mint)) {
+        io.stderr.write('dexterm larp-detected: --live needs a Solana mint\n');
+        return 2;
+    }
+    const dl = createDataLayer({ dbPath });
+    try {
+        const result = await dl.store.enrich([mint]);
+        const row = result.rows[0];
+        if (!row) {
+            io.stderr.write('dexterm larp-detected: no current market record found for that mint\n');
+            return 2;
+        }
+        const now = Date.now(), model = h1Model(), score = model.score(liveFeatures(row));
+        const c = new Canvas(92, 20, THEMES.cyberspace), t = c.theme;
+        c.fill(0, 0, c.w, c.h, ' ', { bg: t.bg });
+        c.fill(0, 0, c.w, 3, ' ', { bg: t.headBg });
+        c.text(3, 1, 'LARP CHECK · GRADED NOW', { fg: t.warn, bg: t.headBg, b: true });
+        c.textR(0, 1, c.w - 3, shortMint(mint), { fg: t.muted, bg: t.headBg });
+        c.text(4, 6, `${score >= LARP_DRAFT_THRESHOLD ? 'HIGH RISK' : 'BELOW HIGH-RISK LINE'} ${Math.round(score * 100)}/100`, { fg: score >= LARP_DRAFT_THRESHOLD ? t.down : t.up, b: true });
+        c.text(4, 9, `${model.id} heuristic · model output · risk flag, not a certificate`, { fg: t.text });
+        c.text(4, 11, `${isoMinute(now)} · LIVE DATA · DexScreener + Jupiter`, { fg: t.muted });
+        c.text(4, 14, 'No later outcome yet. No person, project or wallet is identified.', { fg: t.text });
+        c.text(4, 17, 'Draft only · human review · not financial advice', { fg: t.muted });
+        const view = { kind: 'larp-now', title: `GRADED NOW · ${shortMint(mint)}`, label: 'live', canvas: c,
+            ages: [{ name: 'market', source: 'DexScreener + Jupiter', ageSec: Math.max(0, (now - Math.max(row.token.fetchedAt, row.pair.fetchedAt)) / 1000) }],
+            report: [`coin ${shortMint(mint)}`, `graded now ${Math.round(score * 100)}/100 · ${model.id} heuristic model output`, 'No later outcome yet. Risk flag, not a certificate. Draft only.'],
+        };
+        const saved = writeExport(view, { dir: outDir, now, subject: `${mint.slice(0, 4)}-${mint.slice(-4)}` });
+        io.stdout.write(`graded-now card: ${saved.png}\n`);
+        return 0;
+    }
+    finally {
+        dl.close();
+    }
+}
+export async function larpDetectedCommand(argv, io) {
+    const o = parse(argv);
+    if (o.help || o.h) {
+        io.stdout.write(LARP_DETECTED_HELP + '\n');
+        return 0;
+    }
+    const dbPath = typeof o.db === 'string' ? resolve(o.db) : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    const outDir = typeof o.out === 'string' ? resolve(o.out) : resolve('marketing', 'larp-detected', new Date().toISOString().slice(0, 10));
+    if (typeof o.live === 'string')
+        return liveCard(o.live, outDir, dbPath, io);
+    if (!existsSync(dbPath)) {
+        io.stderr.write(`dexterm larp-detected: no recorder history at ${dbPath}\n`);
+        return 2;
+    }
+    const horizon = typeof o.horizon === 'string' ? Number(o.horizon) : LARP_DRAFT_HORIZON;
+    if (!Number.isFinite(horizon) || horizon <= 0) {
+        io.stderr.write('dexterm larp-detected: --horizon must be positive seconds\n');
+        return 2;
+    }
+    const db = openHistoryReadOnly(dbPath);
+    if (!db) {
+        io.stderr.write('dexterm larp-detected: recorder database could not be opened read-only\n');
+        return 2;
+    }
+    try {
+        const dataset = buildFollowUpDataset(exportRecorded(db, { labelledOnly: true }).records, horizon);
+        if (dataset.flagged.length < LARP_DRAFT_MIN_SAMPLE) {
+            io.stdout.write(`thin sample: ${dataset.flagged.length} unique flagged coins (< ${LARP_DRAFT_MIN_SAMPLE}); wrote no drafts\n`);
+            return 0;
+        }
+        const limit = typeof o.limit === 'string' ? Math.max(0, Math.floor(Number(o.limit))) : 3;
+        const saved = renderHistoryDrafts(dataset, { outDir, limit: Number.isFinite(limit) ? limit : 3 });
+        io.stdout.write(`${datasetLine(dataset)}\nwrote ${saved.drafts.length} draft(s) and ${saved.cards.length} card(s) to ${outDir}\n`);
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}

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/token.js

@@ -473,6 +473,9 @@ export class CandlePrefetcher {
     timer = null;
     busy = false;
     closed = false;
+    settledPromise = Promise.resolve();
+    resolveSettled = null;
+    waitingForSettled = false;
     stamps = [];
     /** Requests actually sent (granted by the limiter). */
     requests = 0;
@@ -494,9 +497,25 @@ export class CandlePrefetcher {
             return;
         if (t && this.target && t.mint === this.target.mint && t.pair === this.target.pair)
             return; // same row: keep waiting
+        this.finishSettled(); // a replaced target can no longer do useful work for its caller
         this.target = t;
+        if (t?.pair)
+            this.settledPromise = new Promise((resolve) => { this.resolveSettled = resolve; });
         this.schedule(this.opts.debounceMs);
     }
+    /**
+     * Resolve after the current hover pass has warmed every immediately available base, explicitly
+     * deferred the next attempt, failed a real request, been replaced, or been cancelled by close(). This
+     * is the completion contract for callers that need to observe the pass result; a debounce timer firing
+     * alone does not mean its sequential requests have finished.
+     */
+    settled() {
+        if (this.resolveSettled) {
+            this.waitingForSettled = true;
+            this.timer?.ref?.();
+        }
+        return this.settledPromise;
+    }
     /** Requests sent in the trailing 60 s. */
     rate() {
         const now = this.opts.now();
@@ -511,6 +530,7 @@ export class CandlePrefetcher {
             clearTimeout(this.timer);
             this.timer = null;
         }
+        this.finishSettled();
     }
     schedule(ms) {
         if (this.timer) {
@@ -521,7 +541,10 @@ export class CandlePrefetcher {
         if (!t || !t.pair || this.closed)
             return;
         this.timer = setTimeout(() => { this.timer = null; void this.step(t); }, Math.max(0, ms));
-        this.timer.unref?.();
+        if (this.waitingForSettled)
+            this.timer.ref?.();
+        else
+            this.timer.unref?.();
     }
     bases() {
         const iv = this.opts.interval();
@@ -541,6 +564,7 @@ export class CandlePrefetcher {
                 continue;
             if (this.rate() >= this.opts.maxPerMin) {
                 this.schedule(this.stamps[0] + 60_000 - this.opts.now() + 50);
+                this.finishSettled(t);
                 return;
             }
             this.busy = true;
@@ -554,9 +578,11 @@ export class CandlePrefetcher {
                     // Try again when the bucket could be idle again (still only if the cursor stays here).
                     const wait = this.dl.limiter.bucket('geckoterminal').delayFor('idle', this.opts.now());
                     this.schedule(Number.isFinite(wait) ? Math.max(250, wait) : 60_000);
+                    this.finishSettled(t);
                     return;
                 }
                 this.sent(); // a real request that failed (HTTP error) still counts against the budget
+                this.finishSettled(t);
                 return;
             }
             finally {
@@ -565,6 +591,17 @@ export class CandlePrefetcher {
             if (this.closed || this.target !== t)
                 return; // the cursor moved on: its own debounce takes over
         }
+        this.finishSettled(t);
+    }
+    finishSettled(t) {
+        if (t && this.target !== t)
+            return;
+        const resolve = this.resolveSettled;
+        this.resolveSettled = null;
+        if (this.waitingForSettled)
+            this.timer?.unref?.();
+        this.waitingForSettled = false;
+        resolve?.();
     }
     sent() {
         this.requests++;

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 {