dexterm-cli 0.1.1 → 0.1.3

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

@@ -0,0 +1,235 @@
+// dexterm — EXPORT / SHARE (task-1401). One key (`E`) renders the current view to a PNG plus a plain-text report in
+// ~/.dexterm/exports (DEXTERM_HOME overrides). Nothing is uploaded, posted or copied anywhere else.
+//
+// The renderer is reusable on purpose (task-1407 PNL cards build on it): give `renderExportPng` / `renderExportText`
+// / `writeExport` an ExportView — any rendered Canvas plus its title, the data label (live / sample / replay) and the
+// data ages — and it frames the view with a header band (title, the label, the export time) and a footer band (every
+// data age, "nothing was uploaded"). The label is never optional: a sample-data frame always says SAMPLE DATA.
+//
+// The frame is rendered CALM (no rain, glitch or scanlines) with no toast, help card or prompt on top, so the PNG
+// is the data, not an effect. PNGs are pure TypeScript (@dexterm/tui rasterize + @dexterm/data encodePng).
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Canvas, rasterizeCanvas, fmtUsd, fmtPrice, fmtPct } from '../../tui/src/index.js';
+import { encodePng } from '../../data/src/index.js';
+import { dextermHome } from "./boot-state.js";
+import { cleanText } from "./screener/rows.js";
+import { rugP, fmtRugP, RUG_MODEL_LABEL } from "./screener/rug.js";
+import { renderFrame } from "./state.js";
+export const LABEL_TEXT = {
+    live: '● LIVE DATA',
+    sample: '◌ SAMPLE DATA · not real prices',
+    replay: '◌ REPLAY · recorded data',
+};
+/** `4s` / `3m` / `2h` / `5d`; `—` when unknown. */
+export function fmtAge(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`;
+}
+const ageText = (a) => (a.ageSec !== null ? `${a.name} ${fmtAge(a.ageSec)}` : `${a.name} ${a.state || 'n/a'}`);
+/** Local timestamp `2026-10-16 01:23:45` (the machine's own clock; the report also carries the ISO time). */
+function localStamp(now) {
+    const d = new Date(now);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** Wrap `parts` joined by ` · ` into lines of at most `w` columns. */
+function wrapParts(prefix, parts, w) {
+    const out = [];
+    let line = prefix;
+    for (const p of parts) {
+        const add = line === prefix ? p : ` · ${p}`;
+        if (line.length + add.length > w && line !== prefix) {
+            out.push(line);
+            line = ' '.repeat(prefix.length) + p;
+        }
+        else
+            line += add;
+    }
+    out.push(line);
+    return out;
+}
+/**
+ * Frame a rendered view: a header band (title, label, export time), the view itself, and a footer band (every data
+ * age, local-only note). Returns a new canvas; the view canvas is not changed.
+ */
+export function composeExportCanvas(v, now) {
+    const src = v.canvas;
+    const w = Math.max(src.w, 60);
+    const t = src.theme;
+    const footer = [
+        ...(v.mint ? [` contract ${v.mint}`] : []),
+        ...wrapParts(v.label === 'replay' ? ' data ages (replay clock): ' : ' data ages: ', v.ages.length ? v.ages.map(ageText) : ['none reported for this view'], w - 1),
+        ` exported locally by dexterm ${localStamp(now)} · nothing was uploaded · not financial advice`,
+    ];
+    const c = new Canvas(w, src.h + 2 + footer.length, t);
+    c.fill(0, 0, w, c.h, ' ', { bg: t.bg });
+    // header band
+    c.fill(0, 0, w, 1, ' ', { bg: t.headBg });
+    const label = ` ${LABEL_TEXT[v.label]} `;
+    const labelFg = v.label === 'live' ? t.up : t.warn;
+    c.text(1, 0, `dexterm export · ${v.title}`, { fg: t.text, bg: t.headBg, b: true }, Math.max(0, w - label.length - 3));
+    c.textR(0, 0, w - 1, label, { fg: labelFg, bg: t.headBg, b: true });
+    // the view
+    for (let y = 0; y < src.h; y++)
+        for (let x = 0; x < src.w; x++) {
+            const i = src.idx(x, y), j = c.idx(x, y + 1);
+            c.ch[j] = src.ch[i];
+            c.fg[j] = src.fg[i];
+            c.bg[j] = src.bg[i];
+            c.at[j] = src.at[i];
+            c.hard[j] = src.hard[i];
+        }
+    for (const s of src.images)
+        c.images.push({ ...s, y: s.y + 1 });
+    c.imageMode = src.imageMode;
+    // footer band
+    const fy = src.h + 1;
+    c.fill(0, fy, w, c.h - fy, ' ', { bg: t.headBg });
+    footer.forEach((line, k) => c.text(0, fy + 1 + k, line, { fg: k === footer.length - 1 ? t.muted : t.text, bg: t.headBg }, w));
+    c.text(0, fy, ` ${LABEL_TEXT[v.label]}`, { fg: labelFg, bg: t.headBg, b: true }, w);
+    return c;
+}
+/** The PNG bytes of a framed view. */
+export function renderExportPng(v, now, opts = {}) {
+    const px = rasterizeCanvas(composeExportCanvas(v, now), opts);
+    return encodePng({ w: px.w, h: px.h, rgba: px.rgba });
+}
+/** The plain-text report: header, label, ages, the view's own lines, the local-only note. */
+export function renderExportText(v, now) {
+    const L = [];
+    L.push(`dexterm export · ${v.title}`);
+    if (v.mint)
+        L.push(`contract    ${v.mint}`);
+    L.push(`data        ${LABEL_TEXT[v.label]}`);
+    L.push(`exported    ${localStamp(now)} (local time) · ${new Date(now).toISOString()}`);
+    L.push(`data ages${v.label === 'replay' ? ' (on the replay clock)' : ''}`);
+    if (!v.ages.length)
+        L.push('  none reported for this view');
+    for (const a of v.ages)
+        L.push(`  ${a.name.padEnd(12)} ${(a.ageSec !== null ? fmtAge(a.ageSec) : a.state || 'n/a').padEnd(14)} ${a.source ?? ''}`.trimEnd());
+    L.push('');
+    L.push(...v.report);
+    L.push('');
+    L.push('Exported locally by dexterm. Nothing was uploaded. Model outputs are labelled as such. Not financial advice.');
+    return L.join('\n') + '\n';
+}
+/** ~/.dexterm/exports (DEXTERM_HOME overrides). */
+export function exportsDir(env = process.env) {
+    return join(dextermHome(env), 'exports');
+}
+const slug = (s) => s.replace(/[^A-Za-z0-9_-]+/g, '').slice(0, 16) || 'view';
+/** Write `<dir>/dexterm-<kind>-<subject>-<stamp>.png` and `.txt` (dir 0700, files 0600). */
+export function writeExport(v, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const dir = opts.dir ?? exportsDir(opts.env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stamp = localStamp(now).replace(/[-: ]/g, '').replace(/^(\d{8})(\d{6})$/, '$1-$2');
+    const base = join(dir, `dexterm-${slug(v.kind)}-${slug(opts.subject ?? v.mint?.slice(0, 6) ?? '')}-${stamp}`);
+    const png = renderExportPng(v, now, opts.raster);
+    writeFileSync(`${base}.png`, png, { mode: 0o600 });
+    writeFileSync(`${base}.txt`, renderExportText(v, now), { mode: 0o600 });
+    return { png: `${base}.png`, txt: `${base}.txt`, bytes: png.length };
+}
+// ------------------------------------------------------------------------------------------ view builders
+const PANEL_NAMES = { market: 'market', candles: 'candles', authorities: 'authorities', holders: 'holders', rugcheck: 'rugcheck', goplus: 'goplus', trades: 'trades' };
+/** Data ages of a live token view, one per panel, from each panel's own fetch time. */
+export function tokenAges(v, now) {
+    return Object.keys(PANEL_NAMES).map((p) => {
+        const s = v.panels[p];
+        const ok = s.fetchedAt !== null && (s.state === 'ok' || s.stale);
+        return {
+            name: PANEL_NAMES[p], source: s.via,
+            ageSec: ok ? (now - s.fetchedAt) / 1000 : null,
+            state: ok ? (s.stale ? 'stale' : null) : s.state === 'needs-key' ? 'needs key' : s.state === 'error' ? `unavailable${s.reason ? ` (${s.reason})` : ''}` : s.state,
+        };
+    });
+}
+const yesNo = (b) => (b === null ? 'unknown' : b ? 'ENABLED' : 'revoked');
+/** The text report body for a live token view: the numbers on screen, each from its panel. */
+export function tokenReport(state, v, now) {
+    const L = [];
+    L.push(`coin        $${cleanText(v.symbol, 16)}${v.name ? ` · ${cleanText(v.name, 40)}` : ''} · ${v.launchpad}`);
+    L.push(`price       ${fmtPrice(v.price)}   5m ${fmtPct(v.chg.m5)}   1h ${fmtPct(v.chg.h1)}   6h ${fmtPct(v.chg.h6)}   24h ${fmtPct(v.chg.h24)}`);
+    L.push(`market cap  ${fmtUsd(v.mcap)}${v.mcapFlagged ? ' (flagged)' : ''}   liquidity ${fmtUsd(v.liq)}   vol 24h ${fmtUsd(v.vol24)}`);
+    L.push(`holders     ${v.holders ?? '—'}   top-10 ${v.top10 === null ? '—' : `${v.top10.toFixed(1)}%`}   dev ${v.dev === null ? '—' : `${v.dev.toFixed(1)}%`}${v.holdersSample ? `   (${v.holdersSample})` : ''}`);
+    L.push(`age         ${v.ageMin === null ? '—' : fmtAge(v.ageMin * 60)}`);
+    L.push(`authorities mint ${yesNo(v.mintAuth)} · freeze ${yesNo(v.freezeAuth)}${v.riskyExtensions.length ? ` · risky extensions: ${v.riskyExtensions.join(', ')}` : ''}`);
+    if (v.rug)
+        L.push(`rugcheck    score ${v.rug.score ?? '—'} · ${v.rug.risks.length} risk${v.rug.risks.length === 1 ? '' : 's'}${v.rug.risks.length ? `: ${v.rug.risks.slice(0, 4).map((r) => cleanText(r.name, 40)).join('; ')}` : ''}${v.rug.lpLockedPct !== null ? ` · LP locked ${v.rug.lpLockedPct.toFixed(0)}%` : ''}`);
+    if (v.flags.length)
+        L.push(`flags       ${v.flags.join(', ')}`);
+    const row = state.screener.rows.find((r) => r.mint === v.mint);
+    const p = row ? rugP(row) : null;
+    if (p !== null)
+        L.push(`p(rug)      ${fmtRugP(p)} · model output: ${RUG_MODEL_LABEL} (a ranking, not a probability; see dexterm backtest)`);
+    const larp = state.larpByMint?.get(v.mint);
+    if (larp)
+        L.push(`LARP check  ${larp.verdict}${larp.confidence !== null ? ` · confidence ${larp.confidence.toFixed(2)}` : ''} · model output, ${fmtAge((now - larp.at) / 1000)} old · a risk flag, not a certificate`);
+    const links = [v.socialLinks.web, v.socialLinks.x, v.socialLinks.tg].filter((x) => !!x).map((u) => cleanText(u, 120));
+    if (links.length)
+        L.push(`links       ${links.join('  ')}  (advertised by the coin; unverified)`);
+    return L;
+}
+/** Plain text of every row of a canvas (the generic report body for screens without a dedicated builder). */
+export function canvasText(c) {
+    const out = [];
+    for (let y = 0; y < c.h; y++)
+        out.push(c.ch.slice(y * c.w, (y + 1) * c.w).join('').trimEnd());
+    while (out.length && out[out.length - 1] === '')
+        out.pop();
+    return out;
+}
+/**
+ * Render the current screen for export: CALM (no rain / glitch / scanlines), and without the toast, help card or
+ * GO-TO prompt on top. The state is restored afterwards, so the live loop is unaffected.
+ */
+export function renderCalmFrame(state, w, h) {
+    const v = state.vfx;
+    const saved = { intensity: v.intensity, toast: v.toast, overlay: state.overlay, goto: state.goto };
+    try {
+        v.intensity = 'off';
+        v.toast = null;
+        state.overlay = null;
+        state.goto = null;
+        return renderFrame(state, w, h);
+    }
+    finally {
+        v.intensity = saved.intensity;
+        v.toast = saved.toast;
+        state.overlay = saved.overlay;
+        state.goto = saved.goto;
+    }
+}
+/** The data label of what is on screen: seeded fixtures are SAMPLE, a `--replay` file is REPLAY, else LIVE. */
+export function dataLabelOf(state) {
+    return state.screener.source === 'fixtures' ? 'sample' : state.screener.source === 'replay' ? 'replay' : 'live';
+}
+/** Build the ExportView for whatever screen is showing (the token screen gets the full per-panel report). */
+export function exportViewFor(state, w, h, now) {
+    const canvas = renderCalmFrame(state, w, h);
+    const label = dataLabelOf(state);
+    const tv = state.screen === 'token' && label !== 'sample' ? state.live?.token?.view ?? null : null;
+    if (tv) {
+        return {
+            kind: 'token', title: `TOKEN · $${cleanText(tv.symbol, 16)}${tv.name ? ` · ${cleanText(tv.name, 32)}` : ''}`, mint: tv.mint,
+            label, canvas, ages: tokenAges(tv, now), report: tokenReport(state, tv, now),
+        };
+    }
+    const sample = label === 'sample' ? [{ name: 'all panels', source: 'seeded fixtures', ageSec: null, state: 'sample data' }] : [];
+    if (state.screen === 'token') {
+        const tk = state.token || state.fx.tokens[state.selected || 0];
+        return { kind: 'token', title: `TOKEN · $${cleanText(tk?.symbol ?? '?', 16)}`, mint: tk?.mint ?? null, label, canvas, ages: sample, report: canvasText(canvas) };
+    }
+    const ages = [...sample];
+    if (label !== 'sample' && state.screener.rows.length) {
+        const ts = state.screener.rows.map((r) => r.fetchedAt).filter((t) => typeof t === 'number' && Number.isFinite(t));
+        if (ts.length) {
+            ages.push({ name: 'rows newest', source: 'screener feed', ageSec: (now - Math.max(...ts)) / 1000 });
+            ages.push({ name: 'rows oldest', source: 'screener feed', ageSec: (now - Math.min(...ts)) / 1000 });
+        }
+    }
+    return { kind: state.screen, title: state.screen.toUpperCase(), mint: null, label, canvas, ages, report: canvasText(canvas) };
+}

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;
     /**
@@ -78,12 +89,16 @@ export class LiveContext {
     started = false;
     fastLaneStarted = false;
     closed = false;
+    /** task-1401: true once close() ran (an async coin-link resolution must not open a token after quit). */
+    get isClosed() { return this.closed; }
     /** Latest SOL/USD, fed from the screener feed each refresh; the fast lane turns on-chain SOL into USD. */
     solUsd = null;
     lastSolFetch = 0;
     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;
@@ -122,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;
@@ -164,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 });
     }
@@ -374,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)
@@ -421,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;