dexterm-cli 0.1.4 → 0.1.5

package/dist/packages/mcp/src/server.js

@@ -17,14 +17,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
-import { createDataLayer, resolveRpcUrl, redactSecrets, defaultDbPath, replayTransport, FixtureStore, extractLinks, bestPairByMint, safeFetch, fetchPage, pageSignals, domainAgeViaRdap, githubRepoActivity, parseHttpUrl, primaryLinks, linkFeatures, gradeLinks, DEFAULT_LINK_RUBRIC, LINK_RUBRIC_MEASURED, parseCoinTarget, resolveCoinTarget, isBareOpen, validateAnalystAction, serializeActionLine, ANALYST_ACTION_TYPES, ACTION_FILE_ENV, ACTION_TOKEN_ENV, } from '../../data/src/index.js';
+import { createDataLayer, resolveRpcUrl, redactSecrets, defaultDbPath, replayTransport, FixtureStore, extractLinks, bestPairByMint, safeFetch, fetchPage, pageSignals, domainAgeViaRdap, githubRepoActivity, parseHttpUrl, primaryLinks, linkFeatures, gradeLinks, DEFAULT_LINK_RUBRIC, LINK_RUBRIC_MEASURED, parseCoinTarget, resolveCoinTarget, isBareOpen, validateAnalystAction, serializeActionLine, ANALYST_ACTION_TYPES, ACTION_FILE_ENV, ACTION_TOKEN_ENV, lamportsToSol, rawToTokens, } from '../../data/src/index.js';
 import { buildDossier } from "./dossier.js";
 import { firewall } from "./firewall.js";
 import { OverlayStore, dextermHome, KB_RULE } from "./user-content.js";
-import { resolveSpectatorSink } from "./spectator-sink.js";
+import { resolveSpectatorSink, readFollowScreen, FOLLOW_NAV_ACTIONS } from "./spectator-sink.js";
+import { resolvePaperAgentDesk } from "./paper-agent.js";
 import { loadAppHelp, getAppHelp, loadDocsKb, getDocs, searchHelp } from "./app-help.js";
 import { assembleTokenDossier, computeBoard, recentNarrativeRows, loadDefaultLexicon, summaryText, buildDigest, tokenRugScorer, h1Model, runBacktest } from '../../packs/src/index.js';
-import { exportRecorded, openHistoryReadOnly } from '../../recorder/src/index.js';
+import { creatorOf, devHistoryLine, exportRecorded, openHistoryReadOnly, queryDevHistory, SERIAL_RUGGER_MIN } from '../../recorder/src/index.js';
 // The default rug-probability scorer (task-1356 Tier 4). H1 is the PRE-REGISTERED heuristic; it is the
 // honest day-one model because no logistic model can be trained until the recorder has ~2 weeks of
 // outcome-labelled history (AI-SUITE-DESIGN §4.3). When a trained `rug-lr-v1` model JSON is shipped it is
@@ -227,7 +228,8 @@ export const TOOLS = [
     { name: 'get_trades', description: 'Recent trades of the most liquid pool (GeckoTerminal tape) with buy/sell aggregates, distinct wallets, and the share of volume from the two most active wallets (wash signal).', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, window: { type: 'string', enum: ['m5', 'h1'] } }, required: ['mint'], additionalProperties: false } },
     { name: 'get_candles', description: 'Candles plus computed summaries: range, drawdown from high, VWAP, change%. Use the summaries rather than doing arithmetic.', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, interval: { type: 'string', enum: ['1m', '5m', '15m', '1h', '4h', '1d'] }, limit: { type: 'integer', minimum: 1, maximum: 300 } }, required: ['mint'], additionalProperties: false } },
     { name: 'rugcheck', description: 'RugCheck-style summary: risks[] (firewalled text), normalised score 0..100, lpLockedPct, tokenProgram.', inputSchema: { type: 'object', properties: { mint: { type: 'string' } }, required: ['mint'], additionalProperties: false } },
-    { name: 'get_dev_history', description: 'Creator address and prior-launch forensics for this mint. Tier-1 fields (prior rugs, bundles, snipers) need a Helius/Birdeye key and are null on the keyless tier; the response says so.', inputSchema: { type: 'object', properties: { mint: { type: 'string' } }, required: ['mint'], additionalProperties: false } },
+    { name: 'get_dev_history', description: 'Creator address and prior-launch forensics for this mint. Prior launches and rugs come from dexterm\'s own recorded history when it has the creator (tier "local-history", see dev_history); bundles and snipers need a Helius/Birdeye key and are null on the keyless tier; the response says so.', inputSchema: { type: 'object', properties: { mint: { type: 'string' } }, required: ['mint'], additionalProperties: false } },
+    { name: 'dev_history', description: 'DEV HISTORY ("has this deployer rugged before?"): the creator wallet\'s track record from dexterm\'s OWN recorded history, keyless. Prior launches the recorder linked to the wallet, their code-only outcome labels (rug / dead / fade / flat / runner; 72 h preferred; keyless-proxy tier), how fast the dev sold its own bag, the serial_rugger flag (>= 2 labelled rugs). Every number carries its source, sample size and age; "unknown" when there is no record. A risk flag from observed history, never a certificate: small samples are common, say the n. Pass a mint (the creator is resolved from the record, Jupiter `dev`, then GoPlus) or a creator wallet.', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, creator: { type: 'string' } }, additionalProperties: false } },
     { name: 'narrative_board', description: 'The NARRATIVE BOARD (task-1356): what is running and what is working across the tokens dexterm has recorded. Deterministic lexicon clustering of recorded launches + trending tokens into narratives (dogs, cats, ai-agents, quantum, …), per narrative: tokens, new launches 1h/24h, 1h/24h volume, pace, median change, top runners, and a documented "what is working" score. No model in the hot path, no token cost; names are matched against a versioned lexicon (X/Telegram-only narratives are missed; the honest unclassified share is shown). window: 1h (default) or 24h; set summary:true for the deterministic spoken morning summary.', inputSchema: { type: 'object', properties: { window: { type: 'string', enum: ['1h', '24h'] }, limit: { type: 'integer', minimum: 1, maximum: 50 }, summary: { type: 'boolean' } }, additionalProperties: false } },
     { name: 'rug_backtest', description: 'Backtest the rug model or the deterministic pack verdicts against RECORDED outcomes (task-1356). Scores the chosen subject over the recorder history at a horizon and reports HONEST metrics: base rate, precision/recall, Brier (vs base-rate Brier), AUC, a 5-bucket calibration table, a per-feed breakdown, and the worst misses/false-alarms with their t0 numbers. kind: "heuristic" (the shipped H1 rug model), "pack_verdicts" (recorded pack rug_p). Leakage is enforced by construction (features are the t0 snapshot, labels are after t0). Returns a note when there is not enough recorded history yet — it never fabricates numbers. Read-only; no model, no token cost.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['heuristic', 'pack_verdicts'] }, horizon_sec: { type: 'integer', enum: [3600, 7200, 21600, 86400, 259200] }, positive_labels: { type: 'array', items: { type: 'string', enum: ['rug', 'dead', 'fade', 'flat', 'runner'] } } }, additionalProperties: false } },
     { name: 'kb_lookup', description: 'Fetch one knowledge-base entry by id (mechanics, patterns, glossary). Entries carry sources, date, confidence and owner. KB never holds facts about a specific live token.', inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false } },
@@ -265,9 +267,26 @@ export const TOOLS = [
     { name: 'set_intensity', description: 'PROPOSE the visual intensity the user confirms with a keypress (persisted, undoable). `intensity`: "off", "normal" or "fever".', inputSchema: { type: 'object', properties: { intensity: { type: 'string', enum: ['off', 'normal', 'fever'] } }, required: ['intensity'], additionalProperties: false } },
     // task-1413 r2: voice speed/name are NOT analyst actions. The `/voice` config path is DENIED_FOR_MODELS —
     // only the keyboard (`<`/`>`, the voice picker) sets it. There is deliberately no set_voice_* tool here.
+    // ---- PAPER agent-trading tools (task-1443). They act ONLY on the SIMULATED paper ledger, inside a mandate
+    // the USER armed; they cannot sign, send, touch a wallet/key, or change a cap. They refuse unless the running
+    // app has armed a mandate AND the user enabled agent paper trading; pause / take-over / stop halts them. Every
+    // call is journaled and visible in the spectator view. Figures are SIMULATED — never present them as a result.
+    { name: 'paper_open_ticket', description: 'Open a SIMULATED (paper) trade ticket for a mint and side, inside the mandate the user armed. Inert until confirmed; nothing is bought or sold here. Needs agent paper trading enabled in the running app. `side` is "buy" or "sell". Paper only — it can never sign or send a real transaction, or change a cap.', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, symbol: { type: 'string' }, decimals: { type: 'integer', minimum: 0, maximum: 18 }, side: { type: 'string', enum: ['buy', 'sell'] } }, required: ['mint', 'symbol', 'decimals', 'side'], additionalProperties: false } },
+    { name: 'paper_size_ticket', description: 'Set the size of an open paper ticket. For a buy, `usd` is the simulated size and is REFUSED if it exceeds the mandate per-trade / per-coin / total caps (the agent can never raise a cap). For a sell, `fraction` is the share of the held paper position in (0, 1]. Paper only.', inputSchema: { type: 'object', properties: { ticketId: { type: 'string' }, usd: { type: 'number' }, fraction: { type: 'number' } }, required: ['ticketId'], additionalProperties: false } },
+    { name: 'paper_confirm', description: 'Confirm a sized paper ticket: re-checks the caps and the pause/stop control, fetches a fresh keyless quote and books the fill into the SIMULATED wallet only. It reports the paper fill and the resulting paper position. It never signs or sends a real transaction. Simulated — label the figures PAPER, never as a result.', inputSchema: { type: 'object', properties: { ticketId: { type: 'string' } }, required: ['ticketId'], additionalProperties: false } },
+    { name: 'paper_close', description: 'Close a fraction of a held SIMULATED (paper) position in one step. `fraction` is the share in (0, 1] (default 1 = all). Books a paper sell only; never signs or sends. Simulated.', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, fraction: { type: 'number' } }, required: ['mint'], additionalProperties: false } },
+    { name: 'paper_positions', description: 'Read the SIMULATED (paper) positions: cost basis, realized paper PnL and token balance per mint. Read-only. Figures are simulated and must be labelled PAPER, never shown as a result.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'paper_pnl', description: 'Read the SIMULATED (paper) PnL snapshot: paper balance, realized paper PnL, cost deployed, per-position rows and the mandate caps in force. Read-only. All figures are simulated — label them PAPER and never show them as a result.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
 ];
-/** The read-only tool surface: every tool except the UI-action ones (task-1313). The only tools a skill may name (task-1377). */
-export const READ_ONLY_TOOLS = TOOLS.map((t) => String(t.name)).filter((n) => !ANALYST_ACTION_TYPES.includes(n));
+/** PAPER agent-trading tools (task-1443). The mutating ones act on the simulated ledger inside the armed mandate. */
+export const PAPER_WRITE_TOOLS = ['paper_open_ticket', 'paper_size_ticket', 'paper_confirm', 'paper_close'];
+export const PAPER_READ_TOOLS = ['paper_positions', 'paper_pnl'];
+const PAPER_TOOLS = new Set([...PAPER_WRITE_TOOLS, ...PAPER_READ_TOOLS]);
+/**
+ * The read-only tool surface: every tool except the UI-action ones (task-1313) and the paper WRITE tools
+ * (task-1443). The only tools a skill may name (task-1377); the paper read tools stay here (they cannot trade).
+ */
+export const READ_ONLY_TOOLS = TOOLS.map((t) => String(t.name)).filter((n) => !ANALYST_ACTION_TYPES.includes(n) && !PAPER_WRITE_TOOLS.includes(n));
 const SKILL_STORE = new OverlayStore({ kind: 'skill', bundled: [{ dir: SKILLS_DIR, layout: 'flat' }], readTools: READ_ONLY_TOOLS, home: () => dextermHome(process.env), onSkip: logSkip('skill') });
 /** Read the action allow-list the CLI put in screen_state.actions (defensive: any shape → empty lists). */
 function allowFrom(screenState) {
@@ -290,6 +309,28 @@ const err = (e) => redactSecrets(e instanceof Error ? e.message : String(e));
 const ageOf = (fetchedAt, source) => ({ fetchedAt: fetchedAt ?? null, ageSec: fetchedAt ? Math.round((Date.now() - fetchedAt) / 1000) : null, source: source ?? null });
 /** A freshly assembled dossier is reused for a few minutes per mint+interval (task-1314). */
 const DOSSIER_TTL_MS = 30_000; // was 180 s: a 3-minute-old price/holder count is not what the analyst should reason from
+/** A JSON-safe view of a paper fill (task-1443): the ledger carries lamports as bigint; convert for the wire. */
+function paperFillView(r) {
+    return {
+        id: r.id, t: r.t, mint: r.mint, symbol: r.symbol, side: r.side, paper: true,
+        solDelta: lamportsToSol(r.solDelta), tokens: rawToTokens(r.tokenDelta < 0n ? -r.tokenDelta : r.tokenDelta, r.decimals),
+        priceSol: r.priceSol, priceUsd: r.priceUsd, priceImpactPct: r.priceImpactPct, slippageBps: r.slippageBps,
+        feeSol: lamportsToSol(r.feeLamports), realizedSol: lamportsToSol(r.realizedLamports), route: r.route,
+    };
+}
+/**
+ * task-1443: the paper wiring for a `dexterm mcp` process. Agent paper trading is for an EXTERNAL agent the user
+ * connected (Claude Code, Cursor, a bot) only: a server the app itself spawned — the in-app analyst or the scan,
+ * marked by the UI-action channel or the spectator-file env — never gets a desk, so the in-app analyst's only
+ * write-shaped tool stays `open_ticket`. Write calls also need a spectator surface watching.
+ */
+export function paperWiring(env, data, spectator) {
+    const spawnedByApp = Boolean(env[ACTION_FILE_ENV] || env.DEXTERM_SPECTATOR_FILE);
+    return {
+        desk: spawnedByApp ? async () => null : () => resolvePaperAgentDesk(data, env),
+        watched: () => spectator.active(),
+    };
+}
 export class McpTools {
     data;
     screenState;
@@ -298,15 +339,38 @@ export class McpTools {
     dbPath;
     narrativeDb = null;
     actionSeq = 0;
+    /** Mints this server returned from screener reads (bounded; task-1443 follow-mode nav targets). */
+    surfaced = new Set();
     /** mint+interval -> last assembled dossier; the data layer caches the underlying fetches too. */
     dossierMemo = new Map();
-    constructor(data, screenState, channel = null, dbPath = null) {
+    /** Resolve the paper agent desk (task-1443); null unless the app enabled agent paper trading on an armed mandate. */
+    paperDesk;
+    /** True while a spectator surface is watching this server (task-1443: paper WRITE calls refuse otherwise). */
+    watched;
+    constructor(data, screenState, channel = null, dbPath = null, paper = null) {
         this.data = data;
         this.screenState = screenState;
         this.channel = channel;
         this.dbPath = dbPath && dbPath !== ':memory:' ? dbPath : null;
+        this.paperDesk = paper?.desk ?? (async () => null);
+        this.watched = paper?.watched ?? (() => false);
     }
     /** Open (once) a read-only handle on the recorder DB; null when there is none (replay / :memory:). */
+    /** 0.1.5 dev history: the recorded track record for a mint's creator (recorder link first, else the hint). */
+    localDevHistory(mint, hint) {
+        const db = this.historyDb();
+        if (!db)
+            return null;
+        const creator = creatorOf(db, mint)?.creator ?? (hint && BASE58.test(hint) ? hint : null);
+        if (!creator)
+            return null;
+        try {
+            return { creator, report: queryDevHistory(db, { creator, mint }) };
+        }
+        catch {
+            return null;
+        }
+    }
     historyDb() {
         if (!this.dbPath)
             return null;
@@ -328,11 +392,23 @@ export class McpTools {
      * data layer and never trades. Returns `{ error }` (with no write) when validation fails.
      */
     uiAction(type, args) {
-        const res = validateAnalystAction({ type, ...args }, allowFrom(this.screenState()));
+        const ss = this.screenState();
+        const allow = allowFrom(ss);
+        // task-1443: in follow mode the agent picks coins from its own screener reads, which the terminal may not be
+        // showing yet; those surfaced mints are valid view-only targets too (same data source as the on-screen rows).
+        if (ss.source === 'follow')
+            allow.mints = [...new Set([...allow.mints, ...this.surfaced])];
+        const res = validateAnalystAction({ type, ...args }, allow);
         if (!res.ok)
             return { error: res.error };
-        if (!this.channel)
+        if (!this.channel) {
+            // task-1443: a terminal following this server (`dexterm --spectate-mcp`) applies a VALIDATED nav call from
+            // the spectator record itself, and only while the agent still has control — no action channel is needed.
+            // View-only moves only: anything that would change user data (watchlist, ticket) or settings stays unavailable.
+            if (ss.source === 'follow' && FOLLOW_NAV_ACTIONS.includes(type))
+                return { ok: true, requested: res.label, note: 'The following dexterm terminal shows this; the user can pause or take over at any time. You cannot confirm, size, or send a trade.' };
             return { error: 'UI actions are not available in this context (no action channel)' };
+        }
         try {
             this.channel.append(serializeActionLine(this.channel.token, ++this.actionSeq, res.action));
         }
@@ -341,6 +417,51 @@ export class McpTools {
         }
         return { ok: true, requested: res.label, note: 'The app applies this and shows "analyst did X". You cannot confirm, size, or send a trade.' };
     }
+    /**
+     * task-1443: a PAPER agent-trading tool. Dispatches to the PaperAgentDesk, which books ONLY the simulated
+     * ledger inside the user-armed mandate, re-checks the pause/stop control and the caps on every call, and
+     * journals everything. Returns `{ error }` when agent paper trading is disabled or a gate/cap refuses it;
+     * it can never sign, send, touch a wallet/key, or change a cap.
+     */
+    async paperTool(name, args) {
+        const desk = await this.paperDesk();
+        if (!desk)
+            return { error: 'agent paper trading is not enabled — the user starts dexterm with `--spectate-mcp --agent-paper <mandate-id>` on a mandate they armed (paper only). No MCP tool can sign or send.', reason: 'not-enabled' };
+        // Every agent paper trade must be visible: a WRITE call refuses unless the app's spectator view is watching
+        // this server (it is, while `--spectate-mcp` runs and the user has not stopped it).
+        if (PAPER_WRITE_TOOLS.includes(name) && !this.watched()) {
+            return { error: 'agent paper trading needs the spectator view open in the running dexterm so every call is visible', reason: 'not-watched' };
+        }
+        try {
+            switch (name) {
+                case 'paper_open_ticket': {
+                    const t = desk.open({ mint: String(args.mint ?? ''), symbol: String(args.symbol ?? ''), decimals: Number(args.decimals), side: args.side === 'sell' ? 'sell' : 'buy' });
+                    return { paper: true, ticket: t, note: 'PAPER ticket opened (simulated). Size it, then confirm. Nothing is signed or sent.' };
+                }
+                case 'paper_size_ticket': {
+                    const t = desk.size(String(args.ticketId ?? ''), { usd: typeof args.usd === 'number' ? args.usd : undefined, fraction: typeof args.fraction === 'number' ? args.fraction : undefined });
+                    return { paper: true, ticket: t };
+                }
+                case 'paper_confirm': {
+                    const r = await desk.confirm(String(args.ticketId ?? ''));
+                    return { paper: true, fill: paperFillView(r.fill), position: r.position, note: 'SIMULATED paper fill — not a result; label it PAPER.' };
+                }
+                case 'paper_close': {
+                    const r = await desk.close({ mint: String(args.mint ?? ''), fraction: typeof args.fraction === 'number' ? args.fraction : undefined });
+                    return { paper: true, fill: paperFillView(r.fill), position: r.position, note: 'SIMULATED paper close.' };
+                }
+                case 'paper_positions': return { paper: true, positions: desk.positions() };
+                case 'paper_pnl': return { ...desk.pnl() };
+                default: return { error: `unknown paper tool ${name}` };
+            }
+        }
+        catch (e) {
+            // A PaperDeskError carries a stable reason (cap name / paused / stopped / takeover / mandate state); the
+            // spectator view sees this as a 'refused' call, and the desk already journaled it.
+            const reason = e.reason;
+            return { error: err(e), ...(typeof reason === 'string' ? { reason } : {}) };
+        }
+    }
     /**
      * task-1413: a read-only view of what the user currently sees. It only reflects the fields the CLI put in
      * screen_state (screen, selected coin, and the `app` block of theme/priceMode/voice/scan/calm/alerts). The
@@ -461,6 +582,8 @@ export class McpTools {
     async call(name, args = {}) {
         if (ANALYST_ACTION_TYPES.includes(name))
             return this.uiAction(name, args);
+        if (PAPER_TOOLS.has(name))
+            return this.paperTool(name, args);
         switch (name) {
             case 'screen_state':
                 return this.screenState();
@@ -472,6 +595,12 @@ export class McpTools {
                 if (!disc.mints.length)
                     return { preset, rows: [], errors: disc.errors };
                 const enr = await this.data.store.enrich(disc.mints.slice(0, limit), { price: false });
+                for (const t of enr.rows) {
+                    this.surfaced.delete(t.mint);
+                    this.surfaced.add(t.mint);
+                }
+                while (this.surfaced.size > 200)
+                    this.surfaced.delete(this.surfaced.values().next().value);
                 return {
                     preset, now: Date.now(),
                     rows: enr.rows.map((t) => ({
@@ -724,12 +853,69 @@ export class McpTools {
                     mintAuthority = (await this.data.detail.mintInfo(mint)).value.mintAuthority;
                 }
                 catch { /* ignore */ }
+                // 0.1.5 dev history: dexterm's own recorded launches for this creator fill prior launches / rugs keylessly.
+                const local = this.localDevHistory(mint, creators[0] ?? null);
+                if (local && local.report.labelled.n > 0) {
+                    return {
+                        mint, creator: local.creator, creators: creators.length ? creators : [local.creator], mintAuthorityAddress: mintAuthority,
+                        devHistory: { launches: local.report.launches.n, rugged: local.report.labelled.rug, bestAth: null, labelled: local.report.labelled.n, source: local.report.source, ageSec: local.report.labelled.ageSec },
+                        snipers: null, bundledPct: null, bundleWallets: null,
+                        tier: 'local-history', note: `prior launches and rugs from dexterm's recorded history (${devHistoryLine(local.report)}); bundles/snipers need a Helius/Birdeye key. Call dev_history for the detail.`,
+                    };
+                }
                 return {
-                    mint, creator: creators[0] ?? null, creators, mintAuthorityAddress: mintAuthority,
+                    mint, creator: creators[0] ?? local?.creator ?? null, creators, mintAuthorityAddress: mintAuthority,
                     devHistory: null, snipers: null, bundledPct: null, bundleWallets: null,
                     tier: 'needs-key', note: goplusErr ? `prior-launch forensics need a Helius/Birdeye key; goplus: ${goplusErr}` : 'prior-launch forensics (rugs, bundles, snipers) need a Helius/Birdeye key and are not available on the keyless tier',
                 };
             }
+            case 'dev_history': {
+                const mint = typeof args.mint === 'string' ? args.mint.trim() : '';
+                let creator = typeof args.creator === 'string' ? args.creator.trim() : '';
+                if (mint && !BASE58.test(mint))
+                    return { error: 'dev_history: mint must be a base58 address' };
+                if (creator && !BASE58.test(creator))
+                    return { error: 'dev_history: creator must be a base58 wallet address' };
+                if (!mint && !creator)
+                    return { error: 'dev_history needs a mint or a creator wallet' };
+                const db = this.historyDb();
+                let creatorSource = creator ? 'argument' : null;
+                if (!creator && mint && db) {
+                    const l = creatorOf(db, mint);
+                    if (l) {
+                        creator = l.creator;
+                        creatorSource = `recorder (${l.source}, linked ${Math.round((Date.now() - l.firstT) / 1000)}s ago)`;
+                    }
+                }
+                if (!creator && mint) {
+                    try {
+                        const r = await this.resolve(mint);
+                        const dev = r.row?.audit?.devAddress;
+                        if (dev) {
+                            creator = dev;
+                            creatorSource = 'jupiter-tokens dev';
+                        }
+                    }
+                    catch { /* next source */ }
+                }
+                if (!creator && mint) {
+                    try {
+                        const c = (await this.data.detail.security(mint)).value.creators ?? [];
+                        if (c[0] && BASE58.test(c[0])) {
+                            creator = c[0];
+                            creatorSource = 'goplus creators';
+                        }
+                    }
+                    catch { /* unknown */ }
+                }
+                const base = { mint: mint || null, disclaimer: 'a risk flag from observed history, not a certificate; labels are keyless-proxy and samples are small (say the n)' };
+                if (!creator)
+                    return { ...base, creator: null, status: 'unknown', note: 'no source named this coin\'s creator (recorder, Jupiter dev, GoPlus)' };
+                if (!db)
+                    return { ...base, creator, creatorSource, status: 'unknown', note: 'no recorded history on this machine: the history recorder keeps creators and outcome labels in the --db file (dexterm record run keeps it fed)' };
+                const report = queryDevHistory(db, { creator, mint: mint || null });
+                return { ...base, creatorSource, ...report, summary: devHistoryLine(report), rule: `serial_rugger = labelled rugs >= ${SERIAL_RUGGER_MIN}` };
+            }
             case 'kb_lookup': {
                 const e = kbAll().find((x) => x.id === args.id);
                 if (!e)
@@ -914,8 +1100,13 @@ function packageVersion() {
 export const SERVER_INFO = { name: 'dexterm', version: packageVersion() };
 function screenStateFromEnv() {
     const raw = process.env.DEXTERM_SCREEN_STATE;
-    if (!raw)
+    if (!raw) {
+        // task-1443: an external server (the user's own agent) reads the snapshot a following terminal publishes.
+        const follow = readFollowScreen(process.env);
+        if (follow)
+            return { ...follow, source: 'follow' };
         return { screen: 'unknown', note: 'the TUI did not pass screen context' };
+    }
     try {
         return JSON.parse(raw);
     }
@@ -952,13 +1143,16 @@ export async function runStdioServer(opts = {}) {
     const channel = channelFile && channelToken
         ? { token: channelToken, append: (line) => fs.appendFileSync(channelFile, line, { mode: 0o600 }) }
         : null;
-    const tools = new McpTools(data, screenStateFromEnv, channel, dbPathForHistory);
     // task-1406 + task-1421: when a running dexterm has a spectator surface open, every tool call is emitted
     // as a SpectatorEvent-shaped JSONL line the TUI tails into its hub (where redaction + the stream live).
     // The sink is active either because the app spawned us with DEXTERM_SPECTATOR_FILE (the in-app analyst) or
     // because the app wrote the ~/.dexterm rendezvous (an external `dexterm mcp` client). When neither holds,
     // active() is false and nothing is built or written — no cost when nobody is watching.
     const spectator = resolveSpectatorSink(process.env);
+    // task-1443: the paper agent desk, resolved lazily per call from the ~/.dexterm rendezvous the running app
+    // writes when the user enabled agent paper trading on a mandate they armed. null (tools refuse) when it is
+    // not enabled; paper WRITE calls also refuse while no spectator surface is watching.
+    const tools = new McpTools(data, screenStateFromEnv, channel, dbPathForHistory, paperWiring(process.env, data, spectator));
     function appendTrace(rec) {
         if (TRACE) {
             try {

package/dist/packages/mcp/src/spectator-sink.js

@@ -7,11 +7,16 @@
 // The record carries NOTHING an agent could act on — it only describes a read/navigation call that
 // already completed. The file is local and token-marked; raw addresses live only on this loopback channel
 // and are redacted before anything leaves the machine.
-import { appendFileSync, readFileSync, statSync } from 'node:fs';
+import { appendFileSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 /** The UI-action tools that move the screen (so follow mode can visibly perform them). */
-const NAV_TOOLS = new Set(['open_token', 'show_in_screener', 'switch_feed', 'add_to_watchlist', 'open_ticket']);
+const NAV_TOOLS = new Set(['open_token', 'show_in_screener', 'switch_feed', 'switch_screen', 'add_to_watchlist', 'open_ticket']);
+/**
+ * task-1443: the view-only UI tools an EXTERNAL agent may use to move a terminal that follows it over MCP. Nothing
+ * here changes user data or settings (no watchlist add, no ticket, no theme/workspace): the screen only moves.
+ */
+export const FOLLOW_NAV_ACTIONS = ['open_token', 'show_in_screener', 'switch_feed', 'switch_screen'];
 function navFor(tool, args) {
     const s = (v) => (typeof v === 'string' ? v : undefined);
     if (tool === 'open_token')
@@ -19,7 +24,10 @@ function navFor(tool, args) {
     if (tool === 'switch_feed')
         return { screen: 'screener', feed: s(args.feed) };
     if (tool === 'show_in_screener')
-        return { screen: 'screener', filter: s(args.filter), highlight: s(args.highlight) };
+        return { screen: 'screener', feed: s(args.preset), filter: s(args.filter), highlight: s(args.highlight) };
+    // task-1443: the task-1413 view-only screen switch moves a following terminal too (e.g. to positions).
+    if (tool === 'switch_screen')
+        return s(args.screen) ? { screen: s(args.screen) } : null;
     if (tool === 'add_to_watchlist')
         return { screen: 'watchlist', mint: s(args.mint) };
     if (tool === 'open_ticket')
@@ -46,6 +54,29 @@ function shortMint(args) {
     const m = typeof args.mint === 'string' ? args.mint : typeof args.symbol === 'string' ? args.symbol : '';
     return m ? ` ${m.length > 10 ? m.slice(0, 6) + '…' : m}` : '';
 }
+/**
+ * task-1443: a readable, PAPER-labelled summary for an agent paper-trading call, so the activity panel says what
+ * the agent did to the simulated ledger (side, size, symbol), not just the tool name. null for any other tool.
+ */
+export function paperSummary(tool, args, result) {
+    if (!tool.startsWith('paper_'))
+        return null;
+    const s = (v) => (typeof v === 'string' ? v.slice(0, 16) : '');
+    const t = (result.ticket ?? {});
+    const f = (result.fill ?? {});
+    switch (tool) {
+        case 'paper_open_ticket': return `PAPER open ${s(args.side)} ticket ${s(args.symbol)}`.trim();
+        case 'paper_size_ticket': return typeof t.usd === 'number' ? `PAPER size ${s(t.symbol)} $${t.usd.toFixed(2)}` : typeof t.fraction === 'number' ? `PAPER size ${s(t.symbol)} ${Math.round(t.fraction * 100)}%` : 'PAPER size';
+        case 'paper_confirm':
+        case 'paper_close': {
+            const sol = typeof f.solDelta === 'number' ? ` ${f.solDelta > 0 ? '+' : ''}${f.solDelta.toFixed(4)} SOL` : '';
+            return `PAPER ${tool === 'paper_close' ? 'close' : s(f.side) || 'fill'} ${s(f.symbol)}${sol}`;
+        }
+        case 'paper_positions': return `PAPER positions (${Array.isArray(result.positions) ? result.positions.length : 0})`;
+        case 'paper_pnl': return 'PAPER pnl';
+        default: return null;
+    }
+}
 /** Build one spectator record for a completed MCP tool call. */
 export function recordForToolCall(opts) {
     const isErr = typeof opts.result.error === 'string';
@@ -55,7 +86,7 @@ export function recordForToolCall(opts) {
         // `nav` phase is the enforcement boundary that prevents a denied MCP call from moving the owner's TUI.
         v: 1, seq: opts.seq, t: (opts.now ?? Date.now)(), phase: isErr ? 'refused' : nav ? 'nav' : 'result',
         agent: opts.agent, transport: 'mcp', tool: opts.tool,
-        summary: isErr ? `error: ${String(opts.result.error).slice(0, 80)}` : `${opts.tool}${shortMint(opts.args)}`,
+        summary: isErr ? `error: ${String(opts.result.error).slice(0, 80)}` : paperSummary(opts.tool, opts.args, opts.result) ?? `${opts.tool}${shortMint(opts.args)}`,
         ms: opts.ms, dataAgeSec: isErr ? null : maxAgeSec(opts.result), nav, ok: !isErr,
         ...(opts.token ? { token: opts.token } : {}),
     };
@@ -88,6 +119,44 @@ function spectatorHome(env) {
     return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
 }
 export function rendezvousPath(env) { return join(spectatorHome(env), MCP_SPECTATOR_RENDEZVOUS); }
+// task-1443: an EXTERNAL `dexterm mcp` server has no DEXTERM_SCREEN_STATE (the running app did not spawn it), so it
+// could never validate a navigation call against "the tokens currently on screen" and every nav tool failed — the
+// following terminal never moved. While a terminal follows over MCP it publishes a reduced snapshot of its screen
+// (screen, visible rows, selection, the action allow-list; no wallet, positions, tickets or app settings) here,
+// refreshed about once a second; the server validates nav calls against it exactly as it does for the in-app analyst.
+/** The follow-mode screen snapshot file name under ~/.dexterm. */
+export const MCP_FOLLOW_SCREEN = 'mcp-screen.json';
+/** A snapshot older than this is ignored (the terminal quit or froze): nav calls then fail closed. */
+export const FOLLOW_SCREEN_MAX_AGE_MS = 10_000;
+export function followScreenPath(env) { return join(spectatorHome(env), MCP_FOLLOW_SCREEN); }
+/** Write the follow-mode snapshot (0600). Best-effort: a write failure only means nav calls fail closed. */
+export function writeFollowScreen(env, snapshot) {
+    try {
+        writeFileSync(followScreenPath(env), JSON.stringify(snapshot) + '\n', { mode: 0o600 });
+    }
+    catch { /* fail closed */ }
+}
+/** Remove the follow-mode snapshot (the terminal quit or stopped following). */
+export function clearFollowScreen(env) {
+    try {
+        rmSync(followScreenPath(env), { force: true });
+    }
+    catch { /* ignore */ }
+}
+/** Read the follow-mode screen snapshot, or null when absent, malformed or stale. Never throws. */
+export function readFollowScreen(env, now = Date.now()) {
+    const path = followScreenPath(env);
+    try {
+        const st = statSync(path);
+        if (now - st.mtimeMs > FOLLOW_SCREEN_MAX_AGE_MS)
+            return null;
+        const o = JSON.parse(readFileSync(path, 'utf8'));
+        return o && typeof o === 'object' && !Array.isArray(o) ? o : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the spectator sink for a `dexterm mcp` server. DEXTERM_SPECTATOR_FILE (the running app spawned us,
  * e.g. the in-app analyst) wins and is always active; otherwise the sink watches the rendezvous file under

package/dist/packages/mcp/src/user-content.js

@@ -84,6 +84,7 @@ export function parseEntryFile(file, origin = 'bundled') {
 const MONEY_WORDS = new Set([
     'trade', 'swap', 'sign', 'signer', 'send', 'arm', 'ticket', 'order', 'transfer', 'withdraw', 'buy', 'sell',
     'confirm', 'execute', 'submit', 'panic', 'cap', 'caps', 'mandate', 'mandates', 'approve', 'pay', 'payment', 'fund',
+    'close', // task-1443: paper_close books a (simulated) sell — a skill may never name it
 ]);
 /** Tools that exist in dexterm and are money-adjacent by name, refused even though the server knows them. */
 export const MONEY_TOOLS = ['open_ticket'];

package/dist/packages/recorder/src/dev-history.js

@@ -0,0 +1,129 @@
+// DEV HISTORY (0.1.5, task-1425): "has this deployer rugged before?" from dexterm's OWN recorded history, keyless.
+// The creator links come from the `creators` table (a keyless source naming the dev when dexterm saw the coin), the
+// outcomes from the recorder's code-only labeler (labels.ts: keyless-proxy tier), the dev-exit timing from the
+// recorded `dev_pct` series. Every number carries its source, sample size and age; no recorded prior launch is
+// `unknown`, never "clean". It is a risk flag from observed history, never a certificate.
+//
+// Point in time: with `asOf`, only links recorded before it and labels already known by then count (a label is known
+// once its observation t1, or t0 + horizon, has passed). The backtest uses this so a coin is never judged on the
+// future (the same leakage rule as export.ts).
+/** Label horizons in preference order: the 72 h label when known, else the longest one known. */
+const PREF_HORIZONS = [259200, 86400, 21600, 7200, 3600];
+/** Dev-exit rule: the dev held more than this % of supply, then this little. */
+export const DEV_EXIT = { heldPct: 0.5, exitPct: 0.1 };
+/** Prior rugs at/over this many = the `serial_rugger` flag (same threshold as the token-dossier pack). */
+export const SERIAL_RUGGER_MIN = 2;
+export const DEV_HISTORY_SOURCE = 'dexterm recorder (keyless creator links + code-only outcome labels)';
+const median = (xs) => {
+    if (!xs.length)
+        return null;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+/** The creator dexterm recorded for `mint`, or null. */
+export function creatorOf(db, mint) {
+    try {
+        const r = db.prepare('SELECT mint, creator, source, first_t, created_at FROM creators WHERE mint = ?').get(mint);
+        return r ? { mint: r.mint, creator: r.creator, source: r.source, firstT: Number(r.first_t), createdAt: r.created_at === null ? null : Number(r.created_at) } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The creator's recorded track record. Never throws: a DB without the tables reads as `unknown`. */
+export function queryDevHistory(db, q) {
+    const asOf = q.asOf ?? Date.now();
+    const empty = {
+        creator: q.creator, status: 'unknown', asOf, source: DEV_HISTORY_SOURCE,
+        launches: { n: 0, newestT: null, ageSec: null },
+        labelled: { n: 0, rug: 0, dead: 0, fade: 0, flat: 0, runner: 0, horizon: '72h preferred', tier: 'keyless-proxy', newestT: null, ageSec: null },
+        rugRate: null, badRate: null, devExit: { n: 0, medianMin: null, within60m: 0 }, serialRugger: false, recent: [],
+    };
+    let links;
+    try {
+        links = db.prepare('SELECT mint, first_t, created_at FROM creators WHERE creator = ? AND first_t <= ? AND mint != ? ORDER BY first_t DESC LIMIT ?')
+            .all(q.creator, asOf, q.mint ?? '', q.limit ?? 300);
+    }
+    catch {
+        return empty;
+    }
+    if (!links.length)
+        return empty;
+    const outStmt = db.prepare("SELECT t0, horizon_sec, t1, label FROM outcomes WHERE mint = ? AND label != 'unobserved' ORDER BY t0 ASC");
+    const symStmt = db.prepare('SELECT symbol FROM token_snapshots WHERE mint = ? AND symbol IS NOT NULL ORDER BY t ASC LIMIT 1');
+    const devStmt = db.prepare('SELECT t, dev_pct FROM token_snapshots WHERE mint = ? AND dev_pct IS NOT NULL AND t <= ? ORDER BY t ASC LIMIT 400');
+    const counts = { rug: 0, dead: 0, fade: 0, flat: 0, runner: 0 };
+    let labelledN = 0, labelledNewest = null;
+    const exits = [];
+    const launches = [];
+    for (const l of links) {
+        const firstT = Number(l.first_t);
+        const createdAt = l.created_at === null ? null : Number(l.created_at);
+        const rows = outStmt.all(l.mint);
+        // the label of the EARLIEST anchor (closest to launch) at the longest horizon already known as of asOf
+        const known = rows.filter((r) => (r.t1 !== null ? Number(r.t1) : Number(r.t0) + Number(r.horizon_sec) * 1000) <= asOf);
+        let label = null, horizonSec = null, knownAt = null;
+        if (known.length) {
+            const t0 = Math.min(...known.map((r) => Number(r.t0)));
+            const at = known.filter((r) => Number(r.t0) === t0);
+            for (const h of PREF_HORIZONS) {
+                const hit = at.find((r) => Number(r.horizon_sec) === h);
+                if (hit) {
+                    label = hit.label;
+                    horizonSec = h;
+                    knownAt = hit.t1 !== null ? Number(hit.t1) : t0 + h * 1000;
+                    break;
+                }
+            }
+        }
+        if (label) {
+            labelledN++;
+            counts[label]++;
+            if (knownAt !== null)
+                labelledNewest = Math.max(labelledNewest ?? 0, knownAt);
+        }
+        let devExitMin = null;
+        if (q.devExit !== false) {
+            const series = devStmt.all(l.mint, asOf);
+            const held = series.findIndex((r) => r.dev_pct > DEV_EXIT.heldPct);
+            if (held >= 0) {
+                const out = series.slice(held + 1).find((r) => r.dev_pct <= DEV_EXIT.exitPct);
+                if (out) {
+                    const from = createdAt ?? Number(series[held].t);
+                    devExitMin = Math.max(0, (Number(out.t) - from) / 60_000);
+                    exits.push(devExitMin);
+                }
+            }
+        }
+        if (launches.length < 10) {
+            const sym = symStmt.get(l.mint)?.symbol ?? null;
+            launches.push({ mint: l.mint, symbol: sym, firstT, createdAt, label, horizonSec, devExitMin });
+        }
+    }
+    const newestT = Number(links[0].first_t);
+    return {
+        ...empty,
+        status: 'ok',
+        launches: { n: links.length, newestT, ageSec: Math.max(0, Math.round((asOf - newestT) / 1000)) },
+        labelled: { ...empty.labelled, n: labelledN, ...counts, newestT: labelledNewest, ageSec: labelledNewest === null ? null : Math.max(0, Math.round((asOf - labelledNewest) / 1000)) },
+        rugRate: labelledN ? counts.rug / labelledN : null,
+        badRate: labelledN ? (counts.rug + counts.dead) / labelledN : null,
+        devExit: { n: exits.length, medianMin: median(exits), within60m: exits.filter((m) => m <= 60).length },
+        serialRugger: counts.rug >= SERIAL_RUGGER_MIN,
+        recent: launches,
+    };
+}
+const ago = (sec) => sec === null ? 'age unknown' : sec < 3600 ? `${Math.max(1, Math.round(sec / 60))}m ago` : sec < 172800 ? `${Math.round(sec / 3600)}h ago` : `${Math.round(sec / 86400)}d ago`;
+/**
+ * The one-line summary every surface shows (DEV panel, rug-signal row, MCP note): counts with the sample size and
+ * the age, or `unknown` with why. Plain wording: a risk flag from observed history, never "rug confirmed" or "safe".
+ */
+export function devHistoryLine(r) {
+    if (r.status === 'unknown')
+        return 'unknown: no prior launch by this wallet in dexterm\'s record';
+    const L = r.labelled;
+    if (!L.n)
+        return `${r.launches.n} prior launch${r.launches.n === 1 ? '' : 'es'} recorded, none labelled yet (newest ${ago(r.launches.ageSec)})`;
+    return `rugged ${L.rug} of ${L.n} labelled prior launches${L.dead ? ` (+${L.dead} dead)` : ''} · ${r.launches.n} recorded · labels ${ago(L.ageSec)}`;
+}

package/dist/packages/recorder/src/index.js

@@ -8,6 +8,7 @@ export * from "./export.js";
 export * from "./open.js";
 export * from "./verdicts.js";
 export * from "./schedule.js";
+export * from "./dev-history.js";
 export { recorderCli, RECORDER_HELP } from "./cli.js";
 /** `--no-recorder` / `DEXTERM_RECORDER=0` resolution: the recorder is on in live mode unless either says no. */
 export function recorderEnabled(env, flagOff) {