dexterm-cli 0.1.5 → 0.1.7

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/mcp-follow.js

@@ -14,11 +14,52 @@
 // kill" are local follow controls: pause/take-over stop the terminal mirroring the agent (the external agent
 // keeps running — we simply stop moving the screen), and kill removes the rendezvous so the server stops
 // emitting. Any user keypress during an agent move takes control, so the human and the agent never fight.
-import { writeFileSync, readFileSync, rmSync, mkdirSync, statSync } from 'node:fs';
+import { writeFileSync, readFileSync, rmSync, mkdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { SpectatorHub, FollowController, SpectatorServer, } from '../../agents/src/index.js';
+import { SpectatorHub, FollowController, SpectatorServer, AgentStory, sanitizeDetail, } from '../../agents/src/index.js';
 import { rendezvousPath, writeFollowScreen, clearFollowScreen } from '../../mcp/src/index.js';
+/**
+ * task-1466: the agent's own words in one JSONL line of a thoughts feed. Understands Claude Code stream-json
+ * (`assistant` messages: text and thinking blocks), the capture harness's brain feed (`{tEpoch, ev}` wrapping one),
+ * and plain `{"thought": "…"}` / `{"text": "…"}` lines. Anything else yields nothing. Text only; never acted on.
+ */
+export function thoughtsOf(line) {
+    const s = line.trim();
+    if (!s || s[0] !== '{' || s.length > 200_000)
+        return [];
+    let o;
+    try {
+        o = JSON.parse(s);
+    }
+    catch {
+        return [];
+    }
+    let t = typeof o.tEpoch === 'number' && Number.isFinite(o.tEpoch) ? o.tEpoch : null;
+    if (o.ev && typeof o.ev === 'object')
+        o = o.ev;
+    if (t === null && typeof o.t === 'number' && Number.isFinite(o.t) && o.t > 1e12)
+        t = o.t;
+    // task-1473: a demo / stand-in feed marks its scripted lines `"demo": true` (the brain view tags them "demo text")
+    if (typeof o.thought === 'string')
+        return [{ text: o.thought, t, ...(o.demo === true ? { demo: true } : {}) }];
+    if (o.type === 'assistant' && o.message && typeof o.message === 'object') {
+        const content = o.message.content;
+        if (!Array.isArray(content))
+            return [];
+        const out = [];
+        for (const b of content) {
+            if (b?.type === 'text' && typeof b.text === 'string')
+                out.push({ text: b.text, t });
+            else if (b?.type === 'thinking' && typeof b.thinking === 'string' && b.thinking.trim())
+                out.push({ text: b.thinking, t });
+        }
+        return out;
+    }
+    if (typeof o.text === 'string' && !o.type)
+        return [{ text: o.text, t }];
+    return [];
+}
 function navLabel(agent, nav) {
     const coin = nav.mint ? ` ${nav.mint.length > 10 ? nav.mint.slice(0, 4) + '…' + nav.mint.slice(-4) : nav.mint}` : '';
     if (nav.screen === 'token')
@@ -45,6 +86,8 @@ function navLabel(agent, nav) {
 export class McpFollowSession {
     hub;
     follow;
+    /** task-1466: the story the spectator v2 HUD draws (phase rail, timeline, thoughts, PAPER trade arc). */
+    story;
     opts;
     rvPath;
     channelPath;
@@ -52,6 +95,7 @@ export class McpFollowSession {
     agentLabel;
     currentAgent;
     offset = 0;
+    thoughtsOffset = 0;
     timer = null;
     stream = null;
     armed = false;
@@ -71,7 +115,8 @@ export class McpFollowSession {
             kickAgent: () => { this.disarm(); return 1; },
         };
         this.follow = new FollowController({ controls, activityCap: Math.max(1, opts.activityCap ?? 200) });
-        this.hub.on((ev) => this.follow.apply(ev));
+        this.story = new AgentStory(this.agentLabel);
+        this.hub.on((ev) => { this.follow.apply(ev); this.story.apply(ev); });
     }
     /** Arm the rendezvous (so a `dexterm mcp` server starts emitting) and begin tailing. Idempotent. */
     async start() {
@@ -133,6 +178,51 @@ export class McpFollowSession {
     }
     /** Read and fold any records appended since the last pump. Public so tests can drive it without timers. */
     pump() {
+        this.pumpThoughts();
+        this.pumpChannel();
+    }
+    /** task-1466: new lines of the agent's own words → the story's thought ribbon (bounded: ≤ 256 KB per pump). */
+    pumpThoughts() {
+        const file = this.opts.thoughtsFile;
+        if (!file)
+            return;
+        let text;
+        try {
+            const st = statSync(file);
+            if (st.size < this.thoughtsOffset)
+                this.thoughtsOffset = 0;
+            if (st.size === this.thoughtsOffset)
+                return;
+            if (st.size - this.thoughtsOffset > 256 * 1024)
+                this.thoughtsOffset = st.size - 256 * 1024; // skip a backlog, keep the tail
+            const fd = openSync(file, 'r');
+            try {
+                const buf = Buffer.alloc(st.size - this.thoughtsOffset);
+                readSync(fd, buf, 0, buf.length, this.thoughtsOffset);
+                text = buf.toString('utf8');
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch {
+            return;
+        }
+        const nl = text.lastIndexOf('\n');
+        if (nl < 0)
+            return;
+        this.thoughtsOffset += Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
+        const now = (this.opts.now ?? Date.now)();
+        for (const line of text.slice(0, nl).split('\n')) {
+            for (const th of thoughtsOf(line))
+                this.story.thought(th.text, th.t ?? now, 'agent', th.demo === true);
+        }
+        try {
+            this.opts.onEvent?.();
+        }
+        catch { /* ignore */ }
+    }
+    pumpChannel() {
         let text;
         try {
             const st = statSync(this.channelPath);
@@ -184,6 +274,7 @@ export class McpFollowSession {
             ms: rec.ms ?? null,
             dataAgeSec: rec.dataAgeSec ?? null,
             nav: rec.nav ?? null,
+            detail: sanitizeDetail(rec.detail),
             ok: rec.ok ?? true,
             t: typeof rec.t === 'number' ? rec.t : undefined,
         });
@@ -225,10 +316,14 @@ export class McpFollowSession {
     takeOver() { const l = this.follow.takeOver(this.currentAgent); this.paused = false; this.control('takeover'); this.opts.onStatus?.(l); return l; }
     resume() { const l = this.follow.resume(this.currentAgent); this.paused = false; this.control('running'); this.opts.onStatus?.(l); return l; }
     kill() { const l = this.follow.kill(this.currentAgent); this.paused = false; this.control('stopped'); this.opts.onStatus?.(l); return l; }
-    control(state) { try {
-        this.opts.onControl?.(state);
+    control(state) {
+        const now = (this.opts.now ?? Date.now)();
+        this.story.setControl(state === 'stopped' ? 'killed' : state, now);
+        try {
+            this.opts.onControl?.(state);
+        }
+        catch { /* never breaks the key loop */ }
     }
-    catch { /* never breaks the key loop */ } }
     /** Any physical keypress while the agent is driving: the human takes over (no fight over the screen). */
     userKey() { if (this.follow.controlState === 'agent')
         this.takeOver(); }
@@ -237,6 +332,8 @@ export class McpFollowSession {
     get screenModel() { return this.follow.screenModel; }
     get streamPort() { return this.stream?.port ?? 0; }
     view() { return this.follow.view(); }
+    /** task-1466: the story at `now` for the HUD. */
+    storyView(now = (this.opts.now ?? Date.now)()) { return this.story.view(now); }
     /** Tear down: stop the timer, remove the rendezvous, close the stream. Safe to call more than once. */
     async stop() {
         if (this.timer) {

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

@@ -9,6 +9,7 @@
 //   dexterm plan journal [--verify] [--export]
 //   dexterm mandate draft [--total 100] [--per-trade 20] [--per-coin 40] [--daily-loss 50]
 //                         [--max-tier keypress|ptt-held|hands-free] [--ttl-hours 4]
+//                         [--max-open 20] [--max-impact 3] [--paper]
 //   dexterm mandate list [--json] | arm <id> | revoke <id>
 //
 // Arming is the only gate: `arm` reads ONE real keystroke in raw mode (ttyKeypress) and refuses a pipe,
@@ -44,7 +45,10 @@ const PLAN_USAGE = `dexterm plan <command>
   journal [--verify] [--export]`;
 const MANDATE_USAGE = `dexterm mandate <command>
   draft [--total 100] [--per-trade 20] [--per-coin 40] [--daily-loss 50]
-        [--max-tier keypress|ptt-held|hands-free] [--ttl-hours 4] [--json]
+        [--max-tier keypress|ptt-held|hands-free] [--ttl-hours 4] [--max-open 20] [--max-impact 3]
+        [--paper] [--json]
+                                     (--paper: a PAPER-ONLY mandate for the agent paper desk, with its own
+                                      paper ceilings; no plan, copy trade or signer can ever use it)
   list [--json]
   arm <id>                           (needs a physical keypress on a TTY; a pipe/agent is refused)
   revoke <id>`;
@@ -203,16 +207,20 @@ export async function runMandate(rest, io) {
                 const num = (n) => (flag(rest, n) !== undefined ? parseAmount(flag(rest, n)) : undefined);
                 const maxTier = flag(rest, '--max-tier');
                 const ttlHours = flag(rest, '--ttl-hours') ? Number(flag(rest, '--ttl-hours')) : undefined;
+                const plain = (n) => (flag(rest, n) !== undefined ? Number(flag(rest, n)) : undefined);
                 const m = svc.draftMandate({
                     totalUsd: num('--total'), perTradeUsd: num('--per-trade'), perCoinUsd: num('--per-coin'),
                     dailyLossUsd: num('--daily-loss'), maxTier, ttlMs: ttlHours ? ttlHours * 3600_000 : undefined,
+                    maxOpenPositions: plain('--max-open'), maxPriceImpactPct: plain('--max-impact'),
+                    ...(has(rest, '--paper') ? { paperOnly: true } : {}),
                 });
                 if (has(rest, '--json')) {
-                    out(JSON.stringify({ id: m.id, budget: m.budget, maxTier: m.maxTier }));
+                    out(JSON.stringify({ id: m.id, budget: m.budget, maxTier: m.maxTier, paperOnly: m.paperOnly === true }));
                     return 0;
                 }
-                out(`drafted ${m.id}`);
+                out(`drafted ${m.id}${m.paperOnly ? '  (PAPER-ONLY: agent paper desk only)' : ''}`);
                 out(`  total ${fmtUsd(m.budget.totalUsd)} · per-trade ${fmtUsd(m.budget.perTradeUsd)} · per-coin ${fmtUsd(m.budget.perCoinUsd)} · daily-loss ${fmtUsd(m.budget.dailyLossUsd)} · maxTier ${m.maxTier}`);
+                out(`  max open ${m.limits.maxOpenPositions} · max price impact ${m.limits.maxPriceImpactPct}%`);
                 out('  DRAFT only — not armed. Arm with: dexterm mandate arm ' + m.id + '  (physical keypress)');
                 return 0;
             }
@@ -228,7 +236,7 @@ export async function runMandate(rest, io) {
                     return 0;
                 }
                 for (const r of rows)
-                    out(`${r.id.padEnd(24)} ${r.status.padEnd(7)} total ${fmtUsd(r.totalUsd)} · reserved ${fmtUsd(r.reservedUsd)} · spent ${fmtUsd(r.spentUsd)} · maxTier ${r.maxTier}`);
+                    out(`${r.id.padEnd(24)} ${r.status.padEnd(7)} total ${fmtUsd(r.totalUsd)} · reserved ${fmtUsd(r.reservedUsd)} · spent ${fmtUsd(r.spentUsd)} · maxTier ${r.maxTier}${r.paperOnly ? ' · PAPER-ONLY' : ''}`);
                 return 0;
             }
             case 'arm': {
@@ -243,7 +251,9 @@ export async function runMandate(rest, io) {
                     errOut(`no such mandate ${id}`);
                     return 1;
                 }
-                out(`Arm standing mandate ${id}? This lets armed plans fire at machine speed from the capped fast wallet.`);
+                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 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,74 @@ 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 = {}) {
+    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 +169,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 +207,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 +236,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 +279,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 +373,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 +477,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 +643,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}`);