dexterm-cli 0.1.6 → 0.2.0

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

@@ -302,7 +302,13 @@ const USAGE = `dexterm mcp [<command>]
                             --print        only print the snippet, never write
                             --node         emit a "node <path> mcp" command (when dexterm is not on PATH)
                             --yes          write without the confirmation prompt
-  doctor                    spawn the server, do the MCP handshake, and list the tools/prompts/resources`;
+  doctor                    spawn the server, do the MCP handshake, and list the tools/prompts/resources
+
+for agent authors: \`dexterm mcp doctor\` lists every tool with its description. Reads (market data, the trade
+ledger: ledger_trades / positions / summary / equity / compare, candidate_dossier, outcomes_lookup, trading_status,
+telegram_status) never change anything; strategy_propose_* and backtest_request only file a proposal the user applies
+or runs; the paper_* tools trade the SIMULATED wallet and only inside a mandate the user armed. No tool can sign, send,
+enable live trading or raise a cap. Docs: https://dexterm.xyz/docs/agents/`;
 /** `dexterm mcp …`. With no subcommand (or an arg the server consumes, e.g. --replay) it runs the server. */
 export async function runMcp(rest, io) {
     const sub = rest[0];

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

@@ -253,7 +253,7 @@ export async function runMandate(rest, io) {
                 }
                 out(row.paperOnly
                     ? `Arm PAPER-ONLY mandate ${id}? This lets the agent paper desk book simulated fills under these caps. No plan, copy trade or signer can use it.`
-                    : `Arm standing mandate ${id}? This lets armed plans fire at machine speed from the capped fast wallet.`);
+                    : `Arm standing mandate ${id}? This lets armed plans fire at machine speed on PAPER (simulated fills; dexterm places no live order).`);
                 out(`  total ${fmtUsd(row.totalUsd)} · per-trade ${fmtUsd(row.perTradeUsd)} · per-coin ${fmtUsd(row.perCoinUsd)} · maxTier ${row.maxTier}`);
                 out('Hold any key to confirm (physical keypress). A pipe or agent cannot arm. Waiting 15s…');
                 const key = await ttyKeypress(io.stdin, 15_000);

package/dist/packages/cli/src/pnl-app.js

@@ -4,17 +4,26 @@
 //   positions  → every coin with fills (newest activity first; ← → cycle), LIVE or PAPER as above
 //   follows    → the selected followed wallet's coins (TRACKED), newest first
 // In the preview: x share to X · t copy as text · s save only · a show/hide wallet · z exact size/band ·
-// f 16:9 ⇄ 1:1 · ← → other coin · esc close. Share = save + clipboard image + X compose intent in the user's own
+// m market cap ⇄ SOL price (task-1518; mcap is the default when the coin's supply is known) · f 16:9 ⇄ 1:1 ·
+// ← → other coin · esc close. Share = save + clipboard image + X compose intent in the user's own
 // browser (pnl-card.ts shareCard); dexterm posts nothing. Nothing here trades, signs or edits a number.
 import { mix } from '../../tui/src/index.js';
-import { computeCard, renderCard, previewCanvas, cardText, paperCardInput, liveCardInput, trackedCardInput, CardError, } from "./pnl-card.js";
+import { computeCard, renderCard, previewCanvas, cardText, paperCardInput, trackedCardInput, cardSupply, mcapView, CardError, } from "./pnl-card.js";
 const MARK_VIA = 'dexscreener';
 function coinMeta(state, mint) {
     const tv = state.live?.token?.view;
     if (tv && tv.mint === mint)
-        return { symbol: tv.symbol, name: tv.name, image: tv.image };
+        return { symbol: tv.symbol, name: tv.name, image: tv.image, launchpad: tv.launchpad ?? null, fdv: tv.fdv ?? null, price: tv.price ?? null };
     const row = state.screener.rows.find((r) => r.mint === mint);
-    return { symbol: row?.symbol ?? null, name: row?.name ?? null, image: row?.image ?? null };
+    return { symbol: row?.symbol ?? null, name: row?.name ?? null, image: row?.image ?? null, launchpad: row?.launchpad ?? null, fdv: row?.fdv ?? null, price: row?.price ?? null };
+}
+/** The market-cap inputs for a coin: its recorded supply (FDV ÷ price, else pump.fun's 1B) and today's SOL/USD. */
+function mcapInputs(state, mint, meta) {
+    const solUsd = state.live?.positions.solUsd() ?? null;
+    return {
+        supply: cardSupply({ mint, launchpad: meta.launchpad, fdv: meta.fdv, price: meta.price, via: 'market data' }),
+        usdPerSol: solUsd && solUsd > 0 ? { usd: solUsd, source: `$${solUsd.toFixed(2)}/SOL now (display conversion)` } : null,
+    };
 }
 function imageOf(state, url) {
     if (!url || !state.images)
@@ -35,7 +44,7 @@ export function markFor(state, mint) {
         return { priceSol: tv.price / solUsd, at: m.fetchedAt, via: `${m.via ?? 'market'} ÷ SOL/USD` };
     return null;
 }
-/** Coins with paper or live fills, newest activity first. */
+/** Coins with paper fills, newest activity first. */
 function tradedCoins(state) {
     const live = state.live;
     if (!live)
@@ -45,8 +54,6 @@ function tradedCoins(state) {
         last.set(mint, { t, symbol }); };
     for (const r of live.wallet.trades(1000))
         see(r.mint, r.t, r.symbol);
-    for (const r of live.livePositions?.records(1000) ?? [])
-        see(r.mint, r.t, r.symbol);
     return [...last.entries()].sort((a, b) => b[1].t - a[1].t).map(([mint, v]) => ({ mint, symbol: v.symbol }));
 }
 /** Open the preview for the current screen. Returns a reason when there is nothing to card. */
@@ -75,15 +82,15 @@ export function openPnl(state) {
         const mint = state.live.token?.view?.mint ?? state.token?.mint ?? null;
         if (!mint)
             return 'open a coin first';
-        const has = (state.live.livePositions?.records(1, mint).length ?? 0) > 0 || state.live.wallet.trades(1000).some((r) => r.mint === mint);
+        const has = state.live.wallet.trades(1000).some((r) => r.mint === mint);
         if (!has)
-            return 'no paper or live fills for this coin yet: PnL cards come from your own recorded trades';
+            return 'no paper fills for this coin yet: PnL cards come from your own recorded trades';
         state.pnl = { origin: 'token', choices: [{ mint, symbol: coinMeta(state, mint).symbol ?? mint.slice(0, 4) }], wallet: null, ...base };
     }
     else if (state.screen === 'positions') {
         const choices = tradedCoins(state);
         if (!choices.length)
-            return 'no paper or live fills yet: B / S on a token to trade, then H here';
+            return 'no paper fills yet: B / S on a token to paper-trade, then H here';
         state.pnl = { origin: 'positions', choices, wallet: null, ...base };
     }
     else
@@ -111,16 +118,12 @@ export async function pnlInput(state, ui) {
         const solUsd = live.positions.solUsd();
         if (!mark && m.priceUsd && m.priceAt && solUsd)
             mark = { priceSol: m.priceUsd / solUsd, at: m.priceAt, via: `${MARK_VIA} ÷ SOL/USD` };
-        return trackedCardInput(copy.trades(ui.wallet), {
-            wallet: ui.wallet, mint: ch.mint, symbol: meta.symbol ?? m.symbol ?? ch.symbol, name: meta.name, decimals, mark,
-            historyAt: st.lastPollAt, complete: stats.sample.complete, image,
-        });
-    }
-    const liveRows = live.livePositions?.fills(ch.mint) ?? [];
-    if (liveRows.length) {
-        return liveCardInput(liveRows, { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, wallet: live.linkedWallet?.publicKey ?? null, mark: markFor(state, ch.mint), image });
+        return { ...trackedCardInput(copy.trades(ui.wallet), {
+                wallet: ui.wallet, mint: ch.mint, symbol: meta.symbol ?? m.symbol ?? ch.symbol, name: meta.name, decimals, mark,
+                historyAt: st.lastPollAt, complete: stats.sample.complete, image,
+            }), ...mcapInputs(state, ch.mint, meta) };
     }
-    return paperCardInput(live.wallet.trades(1000), { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, mark: markFor(state, ch.mint), image });
+    return { ...paperCardInput(live.wallet.trades(1000), { mint: ch.mint, symbol: meta.symbol ?? undefined, name: meta.name, mark: markFor(state, ch.mint), image }), ...mcapInputs(state, ch.mint, meta) };
 }
 /** (Re)build the card for the current choice; on refusal the preview shows the reason instead of a card. */
 export async function loadPnl(state, now = Date.now()) {
@@ -167,6 +170,13 @@ export function pnlKey(ui, key) {
         ui.notice = ui.opts.exactSize ? 'exact SOL size SHOWN on the card' : 'size shown as a band';
         return { kind: 'none' };
     }
+    if (ch === 'm') {
+        const now = ui.stats ? mcapView(ui.stats, ui.opts).basis : (ui.opts.basis ?? 'mcap');
+        ui.opts.basis = now === 'mcap' ? 'price' : 'mcap';
+        const v = ui.stats ? mcapView(ui.stats, ui.opts) : null;
+        ui.notice = ui.opts.basis === 'price' ? 'entry / exit as SOL price' : v?.fallback ?? 'entry / exit as market cap';
+        return { kind: 'none' };
+    }
     if (ch === 'f') {
         ui.opts.aspect = ui.opts.aspect === 'wide' ? 'square' : 'wide';
         return { kind: 'none' };
@@ -181,7 +191,7 @@ export function pnlKey(ui, key) {
         return { kind: 'share', action: 'save' };
     return { kind: 'none' };
 }
-const HINTS = 'x share to X · t copy text · s save · a wallet · z size · f 16:9/1:1 · ←→ coin · esc';
+const HINTS = 'x share to X · t copy text · s save · a wallet · z size · m mcap/price · f 16:9/1:1 · ←→ coin · esc';
 /** The preview overlay: the card itself at cell size when the terminal fits it, else its text; then the keys. */
 export function renderPnlOverlay(c, state) {
     const ui = state.pnl;
@@ -191,7 +201,7 @@ export function renderPnlOverlay(c, state) {
     c.noRain(0, 0, c.w, c.h);
     c.fill(0, 0, c.w, c.h, ' ', { bg: mix(t.bg, '#000000', 0.5) });
     const ch = ui.choices[ui.idx];
-    const head = `PnL CARD · $${ch?.symbol ?? '?'}${ui.choices.length > 1 ? ` (${ui.idx + 1}/${ui.choices.length})` : ''} · ${ui.opts.aspect === 'wide' ? '16:9' : '1:1'} · wallet ${ui.opts.showWallet ? 'SHOWN' : 'hidden'} · size ${ui.opts.exactSize ? 'EXACT' : 'band'}`;
+    const head = `PnL CARD · $${ch?.symbol ?? '?'}${ui.choices.length > 1 ? ` (${ui.idx + 1}/${ui.choices.length})` : ''} · ${ui.opts.aspect === 'wide' ? '16:9' : '1:1'} · wallet ${ui.opts.showWallet ? 'SHOWN' : 'hidden'} · size ${ui.opts.exactSize ? 'EXACT' : 'band'}${ui.stats ? ` · ${mcapView(ui.stats, ui.opts).basis === 'mcap' ? 'mcap' : 'SOL price'}` : ''}`;
     c.text(1, 0, head, { fg: t.text, bg: t.headBg, b: true }, c.w - 2);
     c.fill(0, c.h - 1, c.w, 1, ' ', { bg: t.headBg });
     c.text(1, c.h - 1, ui.busy ? 'working… (esc closes)' : (ui.notice ?? HINTS), { fg: ui.notice ? t.warn : t.muted, bg: t.headBg }, c.w - 2);

package/dist/packages/cli/src/pnl-card.js

@@ -7,12 +7,16 @@
 // Honesty rules, enforced by construction:
 //   - The stamp (PAPER / LIVE / TRACKED WALLET) comes from `CardInput.source` and is drawn by the renderer in three
 //     places (the stamp block, the frame colour, the stamp strip). No option turns it off; an unknown source throws.
-//   - Numbers come only from fills (the paper ledger, the signer's live ledger, a tracked wallet's decoded history).
+//   - Numbers come only from fills (the paper ledger, the trade ledger, a tracked wallet's decoded history).
 //     There is no API that takes a PnL, a price or a size; every figure is computed here from those fills, with
 //     the time window, the fee basis, what was excluded and the data ages printed on the card.
 //   - Wallet addresses (and LIVE tx signatures, which point at the wallet) are hidden unless `showWallet`; size is a
 //     band unless `exactSize`; no balance, no key, no file path is ever drawn.
 //   - Footer: "not financial advice" and the dexterm URL. No performance claims beyond this one position's fills.
+//   - Market cap (task-1518): ENTRY / EXIT are shown as market cap when the token supply is known (`basis: 'mcap'`,
+//     the default then; `basis: 'price'` keeps the SOL price view). Each mcap is a fill-derived price × the supply,
+//     never a quoted mcap, and the card names the supply source (recorded FDV ÷ price, or pump.fun's fixed 1B) and
+//     the USD conversion. Exit mcap is the blended average of every sell; the last sell's mcap is its own labelled row.
 //
 // Rendering reuses the task-1401 exporter stack: a cell Canvas rasterized by @dexterm/tui (the 5×9 bitmap font) and
 // encoded by @dexterm/data. Big type (the stamp, the ticker, the PnL %) is the same font rasterized at a larger
@@ -20,7 +24,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
-import { Canvas, THEMES, rasterizeCanvas, fmtPriceBare, mix } from '../../tui/src/index.js';
+import { Canvas, THEMES, rasterizeCanvas, fmtPriceBare, fmtUsd, fmtNum, mix } from '../../tui/src/index.js';
 import { encodePng, lamportsToSol } from '../../data/src/index.js';
 import { exportsDir, fmtAge } from "./export.js";
 import { cleanText } from "./screener/rows.js";
@@ -41,18 +45,6 @@ export function paperCardInput(records, o) {
         excluded: [], fees: 'simulated network fee included', image: o.image ?? null,
     };
 }
-/** LIVE: the signer's ledger rows (confirmed on-chain fills, swaps only) for one mint. */
-export function liveCardInput(rows, o) {
-    const rs = rows.filter((r) => r.mint === o.mint && r.kind === 'swap');
-    const nets = new Set(rs.map((r) => r.network));
-    const network = nets.size > 1 ? 'mixed' : rs[0]?.network === 'devnet' ? 'devnet' : 'mainnet';
-    return {
-        source: 'live', network, mint: o.mint, symbol: o.symbol ?? rs[0]?.symbol ?? '?', name: o.name ?? null, decimals: rs[0]?.decimals ?? null,
-        fills: rs.map((r) => ({ t: r.t, side: r.side === 'sell' ? 'sell' : 'buy', solDelta: lamportsToSol(BigInt(r.solDelta)), tokenDelta: BigInt(r.tokenDelta), feeSol: lamportsToSol(BigInt(r.feeLamports)), sig: r.signature })),
-        ledger: 'signer live ledger', wallet: o.wallet ?? null, mark: o.mark ?? null,
-        excluded: network === 'mixed' ? ['devnet and mainnet fills are both in the ledger for this coin'] : [], fees: 'network + priority fees included', image: o.image ?? null,
-    };
-}
 /** TRACKED: a followed wallet's decoded swaps for one mint (read-only public history). */
 export function trackedCardInput(trades, o) {
     const all = trades.filter((t) => t.mint === o.mint && t.wallet === o.wallet);
@@ -99,6 +91,78 @@ export function trackedCardInput(trades, o) {
         excluded, fees: 'network fees + tips included (balance deltas)', image: o.image ?? null,
     };
 }
+/** pump.fun mints a fixed 1,000,000,000 supply per coin (none is minted later), so its market cap is price × 1B. */
+export const PUMP_FUN_SUPPLY = 1_000_000_000;
+/**
+ * The supply for the market-cap view: the token's recorded FDV ÷ price when both are known (total supply, so on a
+ * non-pump coin this is a fully diluted cap and says so), else pump.fun's fixed 1B for a pump.fun coin, else null
+ * (the card then stays on the price view; no supply is ever guessed).
+ */
+export function cardSupply(o) {
+    if (o.fdv && o.price && Number.isFinite(o.fdv / o.price) && o.fdv > 0 && o.price > 0) {
+        return { tokens: o.fdv / o.price, source: `recorded FDV ÷ price${o.via ? ` (${o.via})` : ''}` };
+    }
+    if (o.launchpad === 'pump.fun' || ((!o.launchpad || o.launchpad === 'unknown') && o.mint.endsWith('pump'))) {
+        return { tokens: PUMP_FUN_SUPPLY, source: 'pump.fun fixed supply' };
+    }
+    return null;
+}
+/**
+ * AUTOTRADE PAPER: one position's fills from an autotrade run ledger. The desk books in USD, so each fill's SOL leg
+ * is its USD at `solUsd` (said on the card); the market caps come straight from the USD fills × supply, so the SOL
+ * rate changes only the size band, never a cap or the return.
+ */
+export function autotradeCardInput(events, o) {
+    if (!(o.solUsd.usd > 0))
+        throw new CardError('an autotrade card needs a SOL/USD rate to show the USD desk in SOL');
+    const fs = events.filter((e) => e.kind === 'fill' && e.positionId === o.positionId && (e.side === 'buy' || e.side === 'sell') && (e.usd ?? 0) > 0 && (e.tokens ?? 0) > 0);
+    const mint = fs[0]?.mint ?? '';
+    const closed = events.find((e) => e.kind === 'trade_closed' && e.trade?.id === o.positionId);
+    const decimals = o.decimals ?? 6;
+    return {
+        source: 'paper', mint, symbol: o.symbol ?? closed?.trade?.symbol ?? mint.slice(0, 4), name: o.name ?? null, decimals,
+        fills: fs.map((e) => ({
+            t: e.t, side: e.side, solDelta: (e.side === 'buy' ? -1 : 1) * e.usd / o.solUsd.usd,
+            tokenDelta: BigInt(Math.round(e.tokens * 10 ** decimals)) * (e.side === 'buy' ? 1n : -1n), feeSol: null, sig: null,
+        })),
+        ledger: o.runId ? `autotrade paper run ${o.runId}` : 'autotrade paper ledger', wallet: null, mark: o.mark ?? null, excluded: [],
+        fees: `USD paper desk, impact in fills · SOL $${o.solUsd.usd.toFixed(2)} (${o.solUsd.source})`, image: o.image ?? null,
+        supply: o.supply === undefined ? cardSupply({ mint }) : o.supply,
+        usdPerSol: { usd: o.solUsd.usd, source: 'the desk\'s USD fills', native: true },
+    };
+}
+/**
+ * TRADE LEDGER (task-1530): one round trip of the unified ledger as a card. The stamp follows the wallet mode
+ * (paper → PAPER; devnet / live → LIVE with its network), and ENTRY / EXIT use the market-cap basis whenever the
+ * ledger recorded a supply (the same mcap code as every other card). A fill with no SOL leg (the autotrade USD desk)
+ * needs `solUsd`; a fill with no token amount refuses the card rather than guess.
+ */
+export function ledgerCardInput(row, o = {}) {
+    // task-1655: a real-mode row is dexterm's model of a trade it signalled; the real fill is the executor's receipt.
+    // A card would stamp it PAPER or LIVE, and both are wrong, so there is none.
+    if (row.walletMode === 'real')
+        throw new CardError('a real-mode trade: dexterm only modelled this fill (the signal it sent your executor); your executor\'s receipt is the record, so dexterm makes no card for it');
+    const decimals = row.decimals ?? 6;
+    const usdDesk = row.fills.some((f) => f.sol === null);
+    if (usdDesk && !(o.solUsd && o.solUsd.usd > 0))
+        throw new CardError('this trade was booked in USD: a card needs a SOL/USD rate (--sol-usd)');
+    const fills = row.fills.map((f) => {
+        if (!(f.tokens !== null && f.tokens > 0))
+            throw new CardError(`fill ${f.t} has no token amount in the ledger`);
+        const sol = f.sol !== null && !usdDesk ? f.sol : (f.usd ?? 0) / o.solUsd.usd;
+        return { t: f.t, side: f.side, solDelta: (f.side === 'buy' ? -1 : 1) * Math.abs(sol), tokenDelta: BigInt(Math.round(f.tokens * 10 ** decimals)) * (f.side === 'buy' ? 1n : -1n), feeSol: f.feeSol, sig: row.walletMode === 'paper' ? null : f.txSig };
+    });
+    const where = row.source === 'autotrade' ? `autotrade paper run ${row.runId ?? ''}`.trim() : row.source === 'desk' ? 'agent paper desk' : row.source === 'live' ? 'signer live ledger' : 'dexterm paper ledger';
+    return {
+        source: row.walletMode === 'paper' ? 'paper' : 'live', network: row.walletMode === 'paper' ? null : row.walletMode === 'devnet' ? 'devnet' : 'mainnet',
+        mint: row.mint, symbol: row.symbol, name: o.name ?? null, decimals, fills,
+        ledger: `trade ledger · ${where} · ${row.tradeId}`, wallet: null, mark: o.mark ?? null, excluded: [],
+        fees: usdDesk ? `USD paper desk, impact in fills · SOL $${o.solUsd.usd.toFixed(2)} (${o.solUsd.source})` : row.walletMode === 'paper' ? 'simulated network fee included' : 'network + priority fees included',
+        image: o.image ?? null,
+        supply: row.supply ?? cardSupply({ mint: row.mint }),
+        ...(usdDesk ? { usdPerSol: { usd: o.solUsd.usd, source: 'the desk\'s USD fills', native: true } } : o.solUsd ? { usdPerSol: o.solUsd } : {}),
+    };
+}
 /** Cost-basis maths over the fills (average cost, the paper and live ledgers' own rule). Throws CardError when a card would mislead. */
 export function computeCard(input, now) {
     if (input.source !== 'paper' && input.source !== 'live' && input.source !== 'tracked')
@@ -109,7 +173,7 @@ export function computeCard(input, now) {
     if (!fills.some((f) => f.side === 'buy'))
         throw new CardError('no recorded buy for this coin, so there is no cost basis to measure against');
     let held = 0n, peak = 0n, cost = 0, costIn = 0, proceeds = 0, realized = 0, boughtRaw = 0n, soldRaw = 0n, buys = 0, sells = 0, unmatched = 0;
-    let fees = 0, feesKnown = false, firstBuy = Infinity, lastSell = -Infinity;
+    let fees = 0, feesKnown = false, firstBuy = Infinity, lastSell = -Infinity, lastSellAvg = null;
     for (const f of fills) {
         if (f.feeSol !== null) {
             fees += f.feeSol;
@@ -147,6 +211,8 @@ export function computeCard(input, now) {
             cost -= removed;
             held -= matched;
             soldRaw += matched;
+            if (input.decimals !== null)
+                lastSellAvg = got / (Number(matched) / 10 ** input.decimals);
         }
     }
     if (!buys)
@@ -174,7 +240,7 @@ export function computeCard(input, now) {
         input, buys, sells, firstT: fills[0].t, lastT: fills[fills.length - 1].t, open,
         costInSol: costIn, proceedsSol: proceeds, realizedSol: realized, unrealizedSol: unrealized, pnlSol: pnl, pnlPct: costIn > 0 ? pnl / costIn : 0,
         kind: !open ? 'realized' : sells ? 'realized + unrealized' : 'unrealized',
-        entryAvg: boughtW ? costIn / boughtW : null, exitAvg: soldW ? proceeds / soldW : null,
+        entryAvg: boughtW ? costIn / boughtW : null, exitAvg: soldW ? proceeds / soldW : null, lastSellAvg,
         holdMs: Math.max(0, (open ? now : lastSell === -Infinity ? now : lastSell) - (firstBuy === Infinity ? fills[0].t : firstBuy)),
         feesSol: feesKnown ? fees : null, now,
     };
@@ -217,6 +283,66 @@ export function fmtWhen(t) {
 }
 const signedSol = (n) => `${n >= 0 ? '+' : '-'}${Math.abs(n).toFixed(4)} SOL`;
 const short = (a) => (a.length > 10 ? `${a.slice(0, 4)}…${a.slice(-4)}` : a);
+/** `1B` / `998.8M` / `21,000,000` → a short supply figure for the provenance line. */
+const fmtSupply = (n) => (n === PUMP_FUN_SUPPLY ? '1B' : fmtNum(n));
+/** Resolve the basis and the market caps for a card: every figure is a fill-derived SOL price × supply (× USD/SOL). */
+export function mcapView(s, o = {}) {
+    const sup = s.input.supply;
+    const want = o.basis ?? (sup ? 'mcap' : 'price');
+    const none = { basis: 'price', fallback: null, unit: 'SOL', entry: null, exitBlended: null, lastSell: null, mark: null };
+    if (want === 'price')
+        return none;
+    if (!sup || !(sup.tokens > 0))
+        return { ...none, fallback: 'market cap not shown: no token supply recorded, so prices are in SOL' };
+    if (s.input.decimals === null)
+        return { ...none, fallback: 'market cap not shown: token decimals unknown, so prices are in SOL' };
+    const k = sup.tokens * (s.input.usdPerSol && s.input.usdPerSol.usd > 0 ? s.input.usdPerSol.usd : 1);
+    const m = (p) => (p === null || p === undefined || !Number.isFinite(p) ? null : p * k);
+    return {
+        basis: 'mcap', fallback: null, unit: s.input.usdPerSol && s.input.usdPerSol.usd > 0 ? 'USD' : 'SOL',
+        entry: m(s.entryAvg), exitBlended: m(s.exitAvg), lastSell: m(s.lastSellAvg), mark: s.open ? m(s.input.mark?.priceSol) : null,
+    };
+}
+/** `$69.7K` / `$1.23M` in USD, `412.3 SOL` / `1.20K SOL` in SOL. */
+export function fmtMcap(v, unit) {
+    if (v === null)
+        return '—';
+    return unit === 'USD' ? fmtUsd(v) : `${fmtNum(v)} SOL`;
+}
+/** The ENTRY / EXIT rows for the market-cap view (closed: entry, blended exit, last sell when there are 2+ sells). */
+function mcapRows(s, v) {
+    const f = (x) => fmtMcap(x, v.unit);
+    const rows = [['ENTRY mcap', `${f(v.entry)} (avg fill)`]];
+    if (s.open)
+        rows.push(['MARK mcap', f(v.mark)]);
+    else
+        rows.push(['EXIT mcap', s.sells > 1 ? `${f(v.exitBlended)} (blended)` : f(v.exitBlended)]);
+    if (s.sells > 1 || (s.open && s.sells))
+        rows.push(['LAST SELL', `${f(v.lastSell)} mcap`]);
+    return rows;
+}
+/**
+ * The card's own statement of where the caps come from, as two stat rows (the provenance block is full on a LIVE
+ * card with the wallet shown, and OPENED / CLOSED repeat its window line, so these two take their place).
+ */
+function mcapSourceRows(s, v) {
+    const sup = s.input.supply, usd = s.input.usdPerSol;
+    const src = sup.source.startsWith('pump.fun') ? 'pump.fun fixed' : sup.source.startsWith('recorded FDV') ? 'FDV/price' : cleanText(sup.source, 12);
+    return [
+        ['SUPPLY', `${fmtSupply(sup.tokens)} · ${src}`],
+        ['MCAP IN', v.unit === 'SOL' ? 'SOL (no USD rate)' : usd?.native ? 'USD (desk fills)' : `USD at $${usd.usd.toFixed(2)}/SOL`],
+    ];
+}
+/** The provenance line of the market-cap view (or of a fallback to the price view). */
+function mcapLine(s, v) {
+    if (v.fallback)
+        return v.fallback;
+    if (v.basis !== 'mcap' || !s.input.supply)
+        return null;
+    const sup = s.input.supply, usd = s.input.usdPerSol;
+    const conv = v.unit === 'USD' ? ` · USD: ${usd.source}` : ' · in SOL';
+    return `mcap = fill price × ${fmtSupply(sup.tokens)} supply (${sup.source})${conv}`;
+}
 /** The stamp of a source. Exhaustive: anything else throws, so a card can never be drawn without one. */
 export function stampOf(s, t) {
     const src = s.input.source;
@@ -251,6 +377,10 @@ export function provenance(s, o, mode = 'text') {
     if (mode === 'text')
         ages.push(`card made ${fmtWhen(s.now)}`);
     L.push(`data ages: ${ages.join(' · ')}`);
+    // the card states the market-cap source in its stat rows (mcapSourceRows); the text spells it out here
+    const ml = mode === 'text' ? mcapLine(s, mcapView(s, o)) : null;
+    if (ml)
+        L.push(ml);
     if (o.showWallet && i.wallet)
         L.push(`wallet: ${i.wallet}`);
     if (i.source === 'live' && o.showWallet) {
@@ -351,15 +481,22 @@ export function renderCard(s, o = {}) {
         : 'return on SOL spent · net of fees · size shown as a band';
     const dec = s.input.decimals !== null;
     const px = (p) => (p === null ? (dec ? '—' : 'n/a (decimals unknown)') : `${fmtPriceBare(p)} SOL`);
+    const mv = mcapView(s, o);
     const stats = [
-        ['ENTRY avg', px(s.entryAvg)],
-        s.open ? ['MARK', px(s.input.mark?.priceSol ?? null)] : ['EXIT avg', px(s.exitAvg)],
+        ...(mv.basis === 'mcap' ? mcapRows(s, mv) : [
+            ['ENTRY avg', px(s.entryAvg)],
+            s.open ? ['MARK', px(s.input.mark?.priceSol ?? null)] : ['EXIT avg', px(s.exitAvg)],
+        ]),
         ['HOLD', `${fmtHold(s.holdMs)}${s.open ? ' (open)' : ''}`],
         ['SIZE', o.exactSize ? `${s.costInSol.toFixed(4)} SOL in` : `${sizeBand(s.costInSol)} (band)`],
         ['FILLS', `${s.buys} buy${s.buys === 1 ? '' : 's'} · ${s.sells} sell${s.sells === 1 ? '' : 's'}`],
-        ['OPENED', fmtWhen(s.firstT)],
-        ['CLOSED', s.open ? 'still open' : fmtWhen(s.lastT)],
+        ...(mv.basis === 'mcap' ? mcapSourceRows(s, mv) : [
+            ['OPENED', fmtWhen(s.firstT)],
+            ['CLOSED', s.open ? 'still open' : fmtWhen(s.lastT)],
+        ]),
     ];
+    if (mv.fallback)
+        stats.push(['MCAP', mv.fallback.startsWith('market cap not shown: no token supply') ? 'n/a: no supply known' : 'n/a: decimals unknown']);
     const prov = [...provenance(s, o, 'card'), stamp.note];
     const coinTile = (x, y, w, h) => {
         if (s.input.image && s.input.image.w > 0 && s.input.image.h > 0) {
@@ -510,7 +647,11 @@ export function cardText(s, o = {}) {
     L.push(`${s.kind} PnL ${fmtPnlPct(s.pnlPct)} (net of fees)${o.exactSize ? ` · ${signedSol(s.pnlSol)} on ${s.costInSol.toFixed(4)} SOL in` : ` · size ${sizeBand(s.costInSol)} (band)`}`);
     const dec = s.input.decimals !== null;
     const p = (v) => (v === null ? (dec ? '—' : 'n/a') : `${fmtPriceBare(v)} SOL`);
-    L.push(`entry avg ${p(s.entryAvg)} · ${s.open ? `mark ${p(s.input.mark?.priceSol ?? null)}` : `exit avg ${p(s.exitAvg)}`} · hold ${fmtHold(s.holdMs)}${s.open ? ' (open)' : ''} · ${s.buys} buys · ${s.sells} sells`);
+    const mv = mcapView(s, o);
+    const head = mv.basis === 'mcap'
+        ? mcapRows(s, mv).map(([k, v]) => `${k.toLowerCase()} ${v}`).join(' · ')
+        : `entry avg ${p(s.entryAvg)} · ${s.open ? `mark ${p(s.input.mark?.priceSol ?? null)}` : `exit avg ${p(s.exitAvg)}`}`;
+    L.push(`${head} · hold ${fmtHold(s.holdMs)}${s.open ? ' (open)' : ''} · ${s.buys} buys · ${s.sells} sells`);
     L.push(...provenance(s, o));
     L.push(st.note + ' Trading in dexterm is experimental.');
     L.push(`not financial advice · ${DEXTERM_URL}`);

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

@@ -9,11 +9,11 @@
 // changed, otherwise just the last two bars ("tail"), so a live tick costs the page one `series.update`.
 // When the coin is held (task-1323 PositionSource) the VM carries the position row + entry/stop/target levels
 // and the fills of the current position from the paper ledger. Read-only: nothing here can trade.
-import { createPopupManager, loadConfig, nativeShellAvailable, TerminalDock, CHART_INTERVALS } from '../../popup/src/index.js';
+import { createPopupManager, loadConfig, nativeShellAvailable, TerminalDock, CHART_INTERVALS, CHART_MARKS_MAX } from '../../popup/src/index.js';
 import { fmtPrice, fmtNum } from '../../tui/src/index.js';
 import { positionRow } from "./live/trade.js";
 import { signedUsd, signedPctOf, fmtUsdFine, sol as fmtSol, signedSol } from "./screens/positions.js";
-import { supplyRatio, positionPriceCells } from "./display.js";
+import { supplyRatio, positionPriceCells, levelCell } from "./display.js";
 import { chipSegments } from "./screens/pnl-chip.js";
 /** Map the app's active Theme to the popup protocol's theme-token subset. */
 export function popupThemeFrom(t) {
@@ -26,6 +26,11 @@ export function popupThemeFrom(t) {
 /** Most bars one VM carries (the 1m base is 1000 bars; this only guards a future bigger base). */
 export const CHART_MAX_BARS = 1500;
 export const DEFAULT_CHART_PREFS = { style: 'candles', scale: 'auto', indicators: ['volume', 'tape', 'ema9', 'ema21'] };
+/** task-1483: the VM's markers layer: the newest CHART_MARKS_MAX fills (oldest first), and how many older ones were left out. */
+export function chartMarksFrom(on, fills) {
+    const keep = fills.length > CHART_MARKS_MAX ? fills.slice(-CHART_MARKS_MAX) : fills;
+    return { on, fills: keep.map((f) => ({ t: f.t, side: f.side, source: f.source, priceUsd: f.priceUsd, tokens: f.tokens, sol: f.sol })), truncated: fills.length - keep.length };
+}
 const finitePos = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
 /** Token amounts up to trillions (same rule as the terminal's position row). */
 function fmtAmt(n) { return n >= 1e12 ? `${(n / 1e12).toFixed(2)}T` : fmtNum(n); }
@@ -57,9 +62,9 @@ export function positionCells(r, mode = 'price', supply = null) {
     if (r.realizedSol !== 0)
         cells.push({ label: 'REALIZED', value: usd && r.realizedUsd !== null ? signedUsd(r.realizedUsd) : `${signedSol(r.realizedSol)} SOL`, tone: tone(r.realizedSol) });
     if (r.stopUsd !== null)
-        cells.push({ label: 'STOP', value: `${fmtPrice(r.stopUsd)}${r.stopDistPct !== null ? ` ${signedPctOf(r.stopDistPct)}` : ''}`, tone: 'down' });
+        cells.push({ label: 'STOP', value: `${levelCell(mode, supply, r.stopUsd)}${r.stopDistPct !== null ? ` ${signedPctOf(r.stopDistPct)}` : ''}`, tone: 'down' });
     if (r.targetUsd !== null)
-        cells.push({ label: 'TARGET', value: `${fmtPrice(r.targetUsd)}${r.targetDistPct !== null ? ` ${signedPctOf(r.targetDistPct)}` : ''}`, tone: 'up' });
+        cells.push({ label: 'TARGET', value: `${levelCell(mode, supply, r.targetUsd)}${r.targetDistPct !== null ? ` ${signedPctOf(r.targetDistPct)}` : ''}`, tone: 'up' });
     return cells;
 }
 /** The chart's position model from the shared task-1323 selector (PositionSource → positionRow). */
@@ -138,7 +143,7 @@ export function chartVMFromView(v, x = {}) {
     vm.feed = x.feed ?? 'POLL';
     vm.livePrice = x.feed === 'LIVE' && finitePos(x.livePrice) ? x.livePrice : null;
     vm.trades = v.trades.map((t) => ({ t: t.t, side: t.side, usd: t.usd, price: t.price })); // no wallet addresses
-    const mode = x.priceMode === 'mcap' ? 'mcap' : 'price';
+    const mode = x.priceMode === 'price' ? 'price' : 'mcap'; // task-1537: market cap unless the host says price
     const supply = mode === 'mcap' ? supplyRatio(v.price, v.mcap) : null;
     vm.position = x.held ? chartPositionFrom(x.held, tick, x.solUsd ?? null, x.positionKind ?? 'paper', x.fills ?? [], mode, supply) : null;
     vm.prefs = x.prefs ?? DEFAULT_CHART_PREFS;
@@ -147,6 +152,8 @@ export function chartVMFromView(v, x = {}) {
     // task-1366: display only — the bars stay USD prices; the page formats the axis as price × supply in mcap mode
     vm.priceMode = mode;
     vm.supply = supply;
+    if (x.marks)
+        vm.marks = chartMarksFrom(x.marks.on, x.marks.fills); // task-1483
     return vm;
 }
 /** Build the token-detail popup view model from the live TokenView (reused by the openPopup interface / Jarvis). */
@@ -447,6 +454,14 @@ export class TokenPopups {
                     this.push(this.lastView);
                 return;
             }
+            case 'chart.markers': { // task-1483: a display preference the terminal saves; nothing else
+                if (typeof p.on !== 'boolean')
+                    return;
+                this.source?.setChartMarkers?.(p.on);
+                if (this.lastView)
+                    this.push(this.lastView);
+                return;
+            }
             case 'chart.painted': {
                 const ms = Number(p.ms);
                 if (p.kind === 'first' && this.metrics.openedAt !== null && this.metrics.openToFirstPaintMs === null)
@@ -535,7 +550,8 @@ export class TokenPopups {
             prefs: this.prefs,
             now: this.now(),
             image: src.imagePath?.(view) ?? null,
-            priceMode: src.chartAxis?.() ?? src.priceMode?.() ?? 'price', // task-1472: the chart axis drives the popup
+            priceMode: src.chartAxis?.() ?? src.priceMode?.() ?? 'mcap', // task-1472: the chart axis drives the popup
+            marks: src.markFills ? { on: src.chartMarkers?.() ?? true, fills: src.markFills(view.mint) } : null, // task-1483
         });
         vm.chip = chartChipFrom(src.pnlChip?.() ?? null); // task-1473 r2
         const key = vm.seriesKey ?? null;