dexterm-cli 0.1.4 → 0.1.6

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

@@ -25,11 +25,13 @@ import { parseMintTarget, parseCoinTarget, resolveCoinTarget, isBareOpen } from
 import { THEMES, isThemeName, DEFAULT_THEME, THEME_NAMES, Flusher, ENTER_SCREEN, LEAVE_SCREEN, DEFAULT_KEYMAP, Keymap, nextTheme, parseKeys, keyId, detectColorDepth, parseColorDepth, blinkFrame, blinkFrames, stepVfx, pulse, isCalm, fxBusy, blendActivity, ImageLayer, queryTerminal, resolveProtocol, fireMoment, fireInflight, clearInflight, skipMoment, momentKindFor, playMoment, soundOn, breakpoint, fmtUsd as fmtUsdTui, } from '../../tui/src/index.js';
 import { resolveRpcUrl, redactSecrets, defaultDbPath, extraRpcUrls, wsUrlFor, SOLANA_PUBLIC_RPC_WS, parseHttpUrl, validateAnalystAction, ACTION_RATE, ACTION_TIER, configChangeForAction, ImageService, encodePng, SummaryLimiter, buildSummaryWindow, KolStore, Cache, PackError, normalizeHandle, terminalSafe } from '../../data/src/index.js';
 import { Recorder, recorderEnabled, MaintenanceSchedule } from '../../recorder/src/index.js';
-import { makeFixtureState, makeFeedState, syncFeed, renderFrame, isScreenKey, activityFor, SCREEN_NAMES, analystKey, syncAnalyst, pinNewpairsSelection, ANALYST_TAB_KEY, computeNarrativeView, newPlansUi, plansService, plansRows, newFollowsUi, copyService, copyAutoService, MIRROR_DEFAULT_CAP_USD } from "./state.js";
+import { makeFixtureState, makeFeedState, syncFeed, renderFrame, isScreenKey, activityFor, SCREEN_NAMES, analystKey, syncAnalyst, pinNewpairsSelection, ANALYST_TAB_KEY, computeNarrativeView, newPlansUi, plansService, plansRows, newFollowsUi, copyService, copyAutoService, MIRROR_DEFAULT_CAP_USD, pnlChipFor } from "./state.js";
 import { mulberry32, tick, spawnPair, shock } from "./fixtures.js";
 import { createLiveFeed, createReplayFeed } from "./feed.js";
 import { LiveContext, INTERVALS, WATCH_REFRESH_MS, POSITIONS_REFRESH_MS, popupBubbleVM } from "./live/index.js";
+import { FOLLOW_NAV_ACTIONS } from '../../mcp/src/index.js';
 import { McpFollowSession } from "./mcp-follow.js";
+import { AgentPaperSwitch } from "./agent-paper.js";
 import { TOKEN_REFRESH_MS, CandlePrefetcher } from "./live/token.js";
 import { PRESETS, presetSpec } from "./screener/presets.js";
 import { parseSortArg, SORT_KEYS } from "./screener/sort.js";
@@ -37,7 +39,9 @@ import { parseFilter } from "./screener/filter.js";
 import { screenerView, setFilter, setSort, setPreset, stepPreset, clampSelection, openFilterEditor, openSortMenu, filterEditorKey, sortMenuKey, } from "./screener/view.js";
 import { readBootState, bootPlan, recordBoot, bootTrace, dextermHome } from "./boot-state.js";
 import { socialOf, kolOf, trendingRows, kolRows, nextSocialFilter, feedsPopupModel } from "./social/view.js";
-import { TokenPopups, tokenDetailVMFromView } from "./popup.js";
+import { TokenPopups, tokenDetailVMFromView, currentPositionFills } from "./popup.js";
+import { OwnPnlTracker } from "./screens/pnl-chip.js";
+import { positionRow } from "./live/trade.js";
 import { widgetPage, widgetEnabled, syncWidgetPopups } from "./widgets.js";
 import { recordLarpVerdict } from "./larp-record.js";
 import { rulesUiOf, rulesTick, rulesMove, beginRuleInput, saveRuleInput, dryRunNow, removeSelectedRule, toggleSelectedRule, dismissSelectedProposal, actOnSelectedProposal, RULE_INPUT_MAX } from "./rules.js";
@@ -46,11 +50,12 @@ import { copyAlertToDelivery } from "./alerts/format.js";
 import { readTelegramCreds, readDiscordCreds } from "./alerts/creds.js";
 import { launchIntelCells, launchRetryable } from "./live/intel.js";
 import { AnalystSession } from "./analyst/session.js";
+import { analystCliOnPath, parseEngineChoice, resolveEngine } from "./analyst/codex.js";
 import { resolveAnalystResults } from "./analyst/results.js";
 import { parseScanCommand, SCAN_FLAGS, checkScanFlag, SCAN_HELP } from "./scan/command.js";
 import { parseWalletCommand, WALLET_HELP } from "./wallet-command.js";
 import { X_HELP } from "./x-cmd.js";
-import { makeScanUi, MODE_LABEL, SCAN_ACTION_TYPES, SCAN_TICK_MS, SCAN_RECOMPUTE_MS } from "./scan/ui.js";
+import { makeScanUi, scanLog, MODE_LABEL, SCAN_ACTION_TYPES, SCAN_TICK_MS, SCAN_RECOMPUTE_MS } from "./scan/ui.js";
 import { buildObservations, observeSig } from "./scan/observe.js";
 import { cleanText } from "./screener/rows.js";
 import { resolveImagesConfig } from "./images-config.js";
@@ -59,7 +64,8 @@ import { VoiceController, selectStt, selectTts, SayTts, voiceStyleDefaults } fro
 import { LivePlanExecutor, defaultPlansJournalPath } from '../../data/src/trade/plans/index.js';
 import { isWalletAddress, shortAddr, buildMirror, leaderSoldSince, autoSizeCap } from '../../data/src/trade/copy/index.js';
 import { FOLLOW_INPUT_MAX } from "./screens/follows.js";
-import { isPriceMode, configPriceMode, togglePriceMode, priceModeOf, planLevels } from "./display.js";
+import { HUD_MIN_H, hudAnimating } from "./screens/agent-hud.js";
+import { isPriceMode, configPriceMode, togglePriceMode, priceModeOf, planLevels, configChartAxis, setChartAxis, chartAxisOf } from "./display.js";
 import { VERSION } from "./version.js";
 import { initCustom, planWorkspace, planPopupOpens, findWorkspace, nextWorkspaceName, workspaceSlots, saveWorkspace, themeFor, themeByName, cycleTheme, themeNames, CHORD_TTL_MS, MAX_WORKSPACE_NAME } from "./custom.js";
 import { DEFAULT_WORKSPACE, MORNING_HUD, applyAndJournal, policyCheck } from '../../custom/src/index.js';
@@ -101,24 +107,55 @@ export function appStateBlock(state) {
         alerts, // booleans only — never a token, webhook or key
     };
 }
+/**
+ * task-1443: the reduced screen snapshot a terminal following an EXTERNAL agent (`--spectate-mcp`) publishes for
+ * that agent's `dexterm mcp` server: what is on screen plus a VIEW-ONLY nav allow-list. Never the watchlist,
+ * tickets, positions or app settings, and only the four follow nav action types (no watchlist add, no ticket).
+ */
+export function followSnapshot(state) {
+    const ss = buildScreenState(state);
+    const a = ss.actions;
+    return {
+        screen: ss.screen, selected: ss.selected, selectedDetail: ss.selectedDetail, filter: ss.filter, sort: ss.sort,
+        visible: ss.visible, visibleMints: ss.visibleMints,
+        actions: { enabled: a.enabled, mints: a.mints, feeds: a.feeds, sortKeys: a.sortKeys, screens: a.screens, workspaces: [], themes: [], types: [...FOLLOW_NAV_ACTIONS] },
+        now: ss.now,
+    };
+}
 export function buildScreenState(state) {
     const live = state.live;
     const sc = state.screener;
     // The screener and the Analyst-tab coin list both show the filtered/sorted screener view, so the
     // selection + visible rows must come from that same view (task-1313); other screens use the raw pool.
-    const rows = state.screen === 'screener' || state.screen === 'analyst' ? screenerView(sc) : sc.rows;
+    // The new-pairs screen shows the live PumpPortal list (task-1443 capture r2: it used to report the screener pool
+    // here, so an agent watching new pairs could not read what was on screen or what was highlighted).
+    const newPairs = state.screen === 'newpairs' && live ? live.newpairs.list() : null;
+    const rows = state.screen === 'screener' || state.screen === 'analyst' ? screenerView(sc) : newPairs ?? sc.rows;
     const toRow = (r) => {
         const x = r;
         if (!x?.mint)
             return null;
         return { mint: x.mint, symbol: x.symbol ?? '', priceUsd: x.price ?? null, chg1h: x.chg?.h1 ?? null, chg24h: x.chg?.h24 ?? null, liq: x.liq ?? null, vol24: x.vol24 ?? null };
     };
-    const visible = rows.slice(0, 12).map(toRow).filter((r) => r !== null);
+    const toNewPairRow = (r) => {
+        const x = r;
+        if (!x?.mint)
+            return null;
+        return {
+            mint: x.mint, symbol: x.symbol ?? '', priceUsd: x.price ?? null, chg1h: x.chg?.h1 ?? null, chg24h: null, liq: x.liq ?? null, vol24: x.vol ?? null,
+            ageSec: Number.isFinite(x.createdAt) ? Math.max(0, Math.round((Date.now() - x.createdAt) / 1000)) : null,
+            mcap: x.mcap ?? null, chg5m: x.chg?.m5 ?? null, bonding: x.bonding ?? null, buys: x.buys ?? null, sells: x.sells ?? null,
+        };
+    };
+    const mapRow = newPairs ? toNewPairRow : toRow;
+    const visible = rows.slice(0, 12).map(mapRow).filter((r) => r !== null);
     let selected = null;
     if (state.screen === 'token' && live?.token?.view)
         selected = { mint: live.token.view.mint, symbol: live.token.view.symbol };
     else {
-        const r = toRow(rows[state.selected || 0]);
+        // Same pick as the new-pairs screen's own highlight (selectedMint first, then the cursor row).
+        const hit = newPairs && state.selectedMint ? newPairs.find((x) => x.mint === state.selectedMint) : undefined;
+        const r = mapRow(hit ?? rows[state.selected || 0]);
         if (r)
             selected = { mint: r.mint, symbol: r.symbol };
     }
@@ -249,7 +286,7 @@ export function shouldDrawFrame(g) {
         return true;
     if (g.calm)
         return g.onTick;
-    if (g.fxBusy)
+    if (g.fxBusy || g.hud)
         return true;
     return g.frame % g.idleEvery === 0;
 }
@@ -288,6 +325,11 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   --record FILE             save every live response (and the PumpPortal session) to FILE (replay it with --replay)
   --spectate-mcp            follow an MCP agent's allowed navigation in this terminal; Ctrl+P pauses, Ctrl+K stops,
                             and any normal user keypress takes control (refused actions never move the UI)
+  --spectate-thoughts FILE  (with --spectate-mcp) stream the agent's own words into the thought ribbon from a JSONL
+                            file it writes (e.g. claude -p --output-format stream-json); display only, scrubbed
+  --agent-paper MANDATE_ID  (experimental, with --spectate-mcp) let that MCP agent PAPER-trade inside a mandate you
+                            armed: simulated fills only, never signs or sends, never raises a cap; Ctrl+P / Ctrl+K /
+                            any key also pause, stop or take over its paper trading
   --max-requests N          hard cap on live requests for this run (default: none)
   --max-credits N           hard cap on Helius credits for this run (default: 5000)
   --mint MINT|LINK          token to open on the token screen (a CA or a dexscreener / pump.fun / solscan / birdeye link)
@@ -302,6 +344,8 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   --selected N              highlighted row / token index
   --seed N                  fixture PRNG seed (default 7)
   --no-ai                   hide the analyst panel on the token screen
+  --analyst-engine E        auto | claude | codex: which of YOUR installed CLIs runs the analyst (default auto = claude
+                            if installed, else codex; DEXTERM_ANALYST_ENGINE or config analyst.engine too; /engine in chat)
 
   --intensity LEVEL         off | normal | fever (default fever: rain, trails, glitch, blink, scanlines at 30 fps;
                             normal: 15 fps, sparser rain, no idle aberration; off = calm: neon theme, no motion)
@@ -389,14 +433,14 @@ export function parseArgs(argv) {
         screen: null, fixtures: false, replay: null, record: null, filter: null, sort: null, preset: null, maxRequests: 0, maxCredits: 0, db: null,
         mint: null, interval: '1h', listen: 20, verbose: false,
         width: null, height: null, html: null, export: null, theme: DEFAULT_THEME, selected: 0, seed: 7,
-        noAi: false, title: null, plain: false, ansi: false, color: null, tz: null,
+        noAi: false, analystEngine: null, title: null, plain: false, ansi: false, color: null, tz: null,
         calm: false, intensity: null, fps: null, frame: 0, t: 1, event: null, ai: null, mood: null, activity: null, noBoot: false, fit: null, fontPx: null, asciiRain: false, noImages: false,
         scan: false, scanConfig: {},
         noRecorder: false,
         sound: false,
         trade: [], live: true,
         workspace: null, priceMode: null,
-        spectateMcp: false,
+        spectateMcp: false, spectateThoughts: null, agentPaper: null,
         help: false, version: false, unknown: [],
     };
     for (let i = 0; i < argv.length; i++) {
@@ -485,6 +529,13 @@ export function parseArgs(argv) {
         }
         else if (k === '--no-ai')
             a.noAi = true;
+        else if (k === '--analyst-engine') {
+            const s = str();
+            const e = parseEngineChoice(s);
+            if (!e)
+                throw new Error(`unknown analyst engine ${s} (expected auto|claude|codex)`);
+            a.analystEngine = e;
+        }
         else if (k === '--calm')
             a.calm = true;
         else if (k === '--intensity') {
@@ -581,6 +632,15 @@ export function parseArgs(argv) {
         // task-1421: follow an agent driving over MCP (the running terminal moves with it; a read-only stream opens).
         else if (k === '--spectate-mcp')
             a.spectateMcp = true;
+        else if (k === '--spectate-thoughts')
+            a.spectateThoughts = str();
+        // task-1443: agent PAPER trading inside a mandate the user armed (validated against the plans journal at start).
+        else if (k === '--agent-paper') {
+            const s = str();
+            if (!/^[A-Za-z0-9_-]{1,64}$/.test(s))
+                throw new Error(`--agent-paper expects a mandate id (see \`dexterm mandate list\`), got ${JSON.stringify(s.slice(0, 20))}`);
+            a.agentPaper = s;
+        }
         else if (k === '--workspace') {
             const s = str();
             if (!/^[a-z][a-z0-9-]{0,39}(\/[a-z][a-z0-9-]{0,39})?$/.test(s))
@@ -618,6 +678,12 @@ export function parseArgs(argv) {
         throw new Error('--scan needs live data or a recording (drop --fixtures)');
     if (a.scan && a.screen)
         throw new Error('--scan is interactive (drop --screen)');
+    if (a.spectateThoughts && !a.spectateMcp)
+        throw new Error('--spectate-thoughts needs --spectate-mcp (the thought ribbon is part of the follow view)');
+    if (a.agentPaper && !a.spectateMcp)
+        throw new Error('--agent-paper needs --spectate-mcp (every agent paper trade must be visible in this terminal)');
+    if (a.agentPaper && a.db === ':memory:')
+        throw new Error('--agent-paper needs an on-disk --db (the agent books into the same paper wallet)');
     return a;
 }
 /**
@@ -1019,6 +1085,8 @@ export async function main(argv, io = process, proc = process) {
                     });
                     recorder.attach(feed.dl.store);
                     ctx.recorder = recorder;
+                    // 0.1.5 dev history: PumpPortal / RugCheck creators of new pairs go into the creator index too.
+                    ctx.newpairs.onCreator = (mint, creator, source, createdAt) => { recorder.recordCreator(mint, creator, source, undefined, createdAt); };
                 }
                 if (args.verbose)
                     io.stderr.write(`dexterm: rpc ${rpc.provider} (${rpc.basis}) · db ${dbPath} · recorder ${ctx.recorder ? 'on' : 'off'} · live trading ${args.live && !io.env.DEXTERM_OFFLINE ? 'available' : 'off'}\n`);
@@ -1084,6 +1152,7 @@ export async function main(argv, io = process, proc = process) {
         for (const e of state.custom.themeErrors)
             io.stderr.write(`dexterm: ${e}\n`);
         state.priceMode = args.priceMode ?? configPriceMode(state.custom.config); // task-1366: --price-mode wins for the run
+        state.chartAxis = configChartAxis(state.custom.config); // task-1472: default MARKET CAP, `A` toggles + saves
         if (args.workspace) {
             const r = switchWorkspace(state, args.workspace, []);
             if (!r.ok) {
@@ -2428,6 +2497,9 @@ export function applyAction(state, action, stack) {
         case 'display.priceMode':
             state.pendingToast = togglePriceMode(state);
             break; // task-1366: display only, persisted
+        case 'display.chartAxis':
+            state.pendingToast = setChartAxis(state);
+            break; // task-1472: both charts' Y axis, display only, persisted
         case 'theme.next':
             state.theme = state.custom ? cycleTheme(state.custom, state.theme) : nextTheme(state.theme);
             break; // task-1358: user themes join the cycle
@@ -2591,6 +2663,7 @@ export function scanCommand(state, cmd, stack, now = Date.now()) {
             if (!e.start(now))
                 return `AI scan is already on (${MODE_LABEL[e.mode]})`;
             live.scanMeter = scanMeterOf(e, now);
+            scanLog(scan, now, 'start', '', `scan on · observe-only · locks at score ≥ ${e.cfg.minScore} · liquidity ≥ $${Math.round(e.cfg.minLiqUsd / 1000)}K`);
             return `AI scan ON · observe-only · warming up ${e.cfg.warmupS}s · locks at score ≥ ${e.cfg.minScore} · ai ≤ ${e.cfg.maxAiPerHour}/h · Z stop`;
         case 'off': {
             if (!e.on)
@@ -2598,6 +2671,7 @@ export function scanCommand(state, cmd, stack, now = Date.now()) {
             stopTurn();
             const was = e.lock?.symbol;
             e.stop(now);
+            scanLog(scan, now, 'stop', was ?? '', was ? 'scan stopped · released' : 'scan stopped');
             live.scanMeter = null;
             scan.returnTo = null;
             return `AI scan stopped${was ? ` (released ${sym(was)})` : ''}`;
@@ -2610,6 +2684,7 @@ export function scanCommand(state, cmd, stack, now = Date.now()) {
             const locked = e.lock;
             stopTurn();
             e.resume(now);
+            scanLog(scan, now, 'release', locked?.symbol ?? '', `released · cooling down ${Math.round(e.cfg.coinCooldownS / 60)}m · watching for the next coin`);
             live.scanMeter = scanMeterOf(e, now);
             // back from the coin the lock pulled up to where the user was, so the ticker is in view
             if (locked && state.screen === 'token' && live.token?.view.mint === locked.mint)
@@ -2639,6 +2714,50 @@ export function applyScanAnalystAction(state, raw) {
     const res = validateAnalystAction(raw, { ...allow, types: SCAN_ACTION_TYPES });
     return { ok: false, error: res.ok ? 'AI scan mode is observe-only' : res.error };
 }
+/**
+ * The analyst engine for a run (0.1.5): `--analyst-engine`, then DEXTERM_ANALYST_ENGINE, then config
+ * `analyst.engine`, then auto (claude when installed, else codex). Only the user picks it; models cannot.
+ */
+export function analystEngineFor(flag, env, configured, has = (b) => analystCliOnPath(b, env)) {
+    const choice = parseEngineChoice(flag) ?? parseEngineChoice(env.DEXTERM_ANALYST_ENGINE) ?? parseEngineChoice(configured) ?? 'auto';
+    return resolveEngine(choice, has);
+}
+/** `/engine [auto|claude|codex]` in the chat box (0.1.5). Null when the input is not this command. */
+export function parseEngineCommand(q) {
+    const m = /^\/engine(?:\s+(\S+))?\s*$/i.exec(q.trim());
+    if (!m)
+        return null;
+    if (!m[1])
+        return { show: true };
+    const c = parseEngineChoice(m[1]);
+    return c ? { choice: c } : { error: `unknown analyst engine "${m[1].slice(0, 16)}" (use /engine auto|claude|codex)` };
+}
+/**
+ * Apply `/engine`: switch the CLI for NEW conversations this run (cached per-coin chats are dropped so the next
+ * `a` starts on the chosen engine; a running turn finishes where it started). Returns the line to show.
+ */
+export function engineCommand(state, cmd, env, has = (b) => analystCliOnPath(b, env)) {
+    const installed = ['claude', 'codex'].filter((b) => has(b));
+    const list = installed.length ? installed.join(' + ') : 'neither claude nor codex';
+    if ('error' in cmd)
+        return cmd.error;
+    const cur = state.analystEngine ?? 'claude';
+    if ('show' in cmd)
+        return `analyst engine: ${cur} · installed: ${list} · /engine claude|codex|auto switches (config analyst.engine keeps it)`;
+    const next = resolveEngine(cmd.choice, has);
+    if (cmd.choice !== 'auto' && !has(next))
+        return `${next} is not installed (installed: ${list}); ${next === 'codex' ? 'npm i -g @openai/codex && codex login' : 'install Claude Code, then run claude once to log in'}`;
+    if (next !== cur) {
+        for (const [k, sess] of state.analystByMint ?? []) {
+            if (!sess.busy)
+                state.analystByMint.delete(k);
+        }
+        if (state.analyst && !state.analyst.busy && state.analyst.engine !== next)
+            state.analyst = null;
+    }
+    state.analystEngine = next;
+    return `analyst engine: ${next} (your own ${next} CLI and login) for new conversations · set analyst.engine in config.json to keep it`;
+}
 /**
  * The ONE way a scan-driven analyst conversation is built (task-1324; the loop and the safety tests both
  * use it): the locked coin as the selected coin, `actionTypes: []` (observe-only at the validator, the
@@ -2652,7 +2771,7 @@ export function createScanSession(state, mint, symbol, hooks = {}, deps = {}) {
         const type = typeof raw.type === 'string' ? raw.type.replace(/[^a-z_]/gi, '').slice(0, 24) : '?';
         hooks.onBlocked?.(type, r.error ?? 'refused');
     };
-    return new AnalystSession({ skill: 'token-dossier', mint, symbol, screenState: ss, onAction, actionTypes: SCAN_ACTION_TYPES, scan: true }, hooks.onChange ?? (() => { }), deps);
+    return new AnalystSession({ skill: 'token-dossier', mint, symbol, screenState: ss, onAction, actionTypes: SCAN_ACTION_TYPES, scan: true, ...(state.analystEngine === 'codex' ? { engine: 'codex' } : {}) }, hooks.onChange ?? (() => { }), deps);
 }
 /**
  * Resolve a mint to an openable seed from what the app already knows (screener view → new pairs →
@@ -2908,6 +3027,61 @@ export function applyAnalystAction(state, raw, stack) {
     times.push(now);
     return { ok: true, label: res.label };
 }
+/**
+ * task-1466: the price this terminal itself shows for a coin, to mark the followed agent's open PAPER position (the
+ * HUD's live PnL): the open token's push price (LIVE) or polled price, else the screener row's price. null if the
+ * terminal has no price for it. Never the agent's own number.
+ */
+export function markPriceFor(state, mint) {
+    const live = state.live;
+    if (live?.token?.view.mint === mint) {
+        const px = (live.badgeFor(mint) === 'LIVE' ? live.livePrice(mint) : null) ?? live.token.view.price;
+        if (typeof px === 'number' && Number.isFinite(px) && px > 0)
+            return px;
+    }
+    const row = state.screener.rows.find((r) => r.mint === mint);
+    if (row && typeof row.price === 'number' && Number.isFinite(row.price) && row.price > 0)
+        return row.price;
+    // task-1473: the held coin scrolled out of the list (run25): its fast-lane push price (the held mint is pinned there)
+    const fast = live?.livePrice(mint) ?? null;
+    return typeof fast === 'number' && Number.isFinite(fast) && fast > 0 ? fast : null;
+}
+let ownOpenedMemo = null;
+/**
+ * task-1473 r2: the user's OWN held position for the AI-scan PnL chip, marked with this terminal's own price (same
+ * task-1323 position row the token screen uses): the scan's locked coin when held, else the open token, else the
+ * first open mint (live first). null when flat. Reads the ledgers only (memoised); never trades, sizes or signs.
+ */
+export function ownHeldSample(state, now) {
+    const live = state.live;
+    if (!live)
+        return null;
+    const src = live.positionSource;
+    const open = src.openMints();
+    if (open.length === 0)
+        return null;
+    const prefer = [state.scan?.engine.lock?.mint, live.token?.view.mint].filter((m) => !!m);
+    const mint = prefer.find((m) => open.includes(m)) ?? open[0];
+    const held = src.held(mint);
+    if (!held)
+        return null;
+    const r = positionRow(held, markPriceFor(state, mint), state.sol?.price ?? src.solUsd());
+    if (!ownOpenedMemo || ownOpenedMemo.mint !== mint || now - ownOpenedMemo.at > 5000) {
+        let t = null;
+        try {
+            t = currentPositionFills([...(live.livePositions?.records(200, mint) ?? []), ...live.wallet.trades(500).filter((x) => x.mint === mint)])[0]?.t ?? null;
+        }
+        catch {
+            t = null;
+        }
+        ownOpenedMemo = { mint, at: now, t };
+    }
+    return {
+        mint, symbol: held.symbol, kind: held.kind === 'live' ? 'live' : 'paper',
+        entryUsd: r.avgEntryUsd, markUsd: r.priceUsd, pnlPct: r.unrealizedPct, pnlUsd: r.unrealizedUsd,
+        openedAt: ownOpenedMemo.t, targetUsd: r.targetUsd,
+    };
+}
 /**
  * task-1421: move the REAL terminal to mirror an agent's navigation (follow mode, on the owner's own
  * machine). This is the same VIEW-ONLY navigation the analyst / go-to path uses — open a token, switch
@@ -3476,7 +3650,14 @@ export function terminalGuard(io, onFatal = () => { }, proc = process, hooks = {
         proc.exit(1);
     };
     const onExit = () => restore();
-    const onSignal = (sig) => { restore(); proc.exit(sig === 'SIGTERM' ? 143 : 129); };
+    const onSignal = (sig) => {
+        restore();
+        try {
+            hooks.onSignal?.();
+        }
+        catch { /* cleanup is best-effort; the exit still happens */ }
+        proc.exit(sig === 'SIGTERM' ? 143 : 129);
+    };
     const onTerm = () => onSignal('SIGTERM');
     const onHup = () => onSignal('SIGHUP');
     let installed = false;
@@ -3513,6 +3694,8 @@ export function fpsFor(args, intensity) {
 const SYNC_ON = '\x1b[?2026h';
 const SYNC_OFF = '\x1b[?2026l';
 export function interactive(state, io, depth, args, proc = process) {
+    // 0.1.5: the analyst engine for new conversations (the user's own claude or codex CLI; never a shipped key).
+    state.analystEngine ??= analystEngineFor(args.analystEngine, io.env, state.custom?.config.analyst?.engine);
     const out = io.stdout;
     const inp = io.stdin;
     const rnd = mulberry32(99);
@@ -3816,6 +3999,9 @@ export function interactive(state, io, depth, args, proc = process) {
         // task-1421: the MCP follow session (set below when `--spectate-mcp` is on). Declared here so the quit /
         // terminal-guard teardown closures can stop it.
         let followSession = null;
+        let lastHudMark = null; // task-1466: the last terminal price that marked the agent's PAPER position
+        // task-1443: `--agent-paper <mandate-id>` (with --spectate-mcp) lets that agent PAPER-trade inside the mandate.
+        const agentPaper = args.spectateMcp && args.agentPaper ? new AgentPaperSwitch({ env: io.env, mandateId: args.agentPaper, db: args.db ?? defaultDbPath(io.env) }) : null;
         // Idle economy (task-1303, retuned for task-1319 AC3): between events the ambient rain redraws at
         // IDLE_FPS instead of the full frame cap, cutting idle CPU. A keypress opens a KEY_WAKE_S full-rate
         // window (`wakeUntil`) so input and transitions stay smooth; data landings paint at once on their own
@@ -3844,10 +4030,13 @@ export function interactive(state, io, depth, args, proc = process) {
                     say(`trade moment failed: ${describeError(e)}`, 'warn');
                 }
             };
-        const guard = terminalGuard(io, () => { done = true; prefetcher?.close(); if (timer)
-            clearInterval(timer); void followSession?.stop(); state.analyst?.cancel(); if (state.analystByMint)
+        const teardown = () => { done = true; prefetcher?.close(); if (timer)
+            clearInterval(timer); void followSession?.stop(); agentPaper?.stop(); state.analyst?.cancel(); if (state.analystByMint)
             for (const s of state.analystByMint.values())
-                s.cancel(); state.popups?.shutdown(); voice?.disable(); images?.close(); live?.close(); feed?.close(); }, proc, { beforeLeave: () => layer?.teardown() ?? '' });
+                s.cancel(); state.popups?.shutdown(); voice?.disable(); images?.close(); live?.close(); feed?.close(); };
+        // task-1443: SIGTERM/SIGHUP (a closed terminal window) runs the same teardown as a fatal error, so the agent-paper
+        // rendezvous, the spectator rendezvous and the --record file never outlive the terminal that owns them.
+        const guard = terminalGuard(io, teardown, proc, { beforeLeave: () => layer?.teardown() ?? '', onSignal: teardown });
         let lastTokenRefresh = 0;
         let lastWatchRefresh = 0;
         let lastPositionsRefresh = 0;
@@ -4041,11 +4230,22 @@ export function interactive(state, io, depth, args, proc = process) {
                     }
                     scheduleDraw();
                 },
-                onStatus: (line) => { say(line, 'ai', 4); scheduleDraw(); },
+                // task-1466: the HUD dock says what the agent did; the toast is only the fallback for a terminal too short for it.
+                onStatus: (line) => { if (size()[1] < HUD_MIN_H)
+                    say(line, 'ai', 4); scheduleDraw(); },
                 onEvent: () => scheduleDraw(),
+                onControl: agentPaper ? (st) => agentPaper.control(st) : undefined,
+                snapshot: () => followSnapshot(state),
+                thoughtsFile: args.spectateThoughts ?? undefined,
             });
+            // task-1466 spectator v2: the agent HUD (phase rail, heartbeat, thought ribbon, call timeline, the PAPER
+            // execution moment, pause / kill) draws over this terminal while it follows. Calm mode = reduced motion.
+            state.agentHud = { story: followSession.story, clock: () => Date.now(), dataLabel: args.replay ? 'REPLAY DATA' : null };
             void followSession.start();
-            say('following agents over MCP · ctrl+p pause · ctrl+k stop · any key takes over', 'ai', 6);
+            if (size()[1] < HUD_MIN_H)
+                say('following agents over MCP · ctrl+p pause · ctrl+k stop · any key takes over', 'ai', 6);
+            if (agentPaper)
+                say(agentPaper.start(), 'ai', 8);
         }
         // Launch a real Claude analyst session when a key asked for one (applyAction cannot spawn). A
         // `question` means start it as a chat turn, not a paid structured skill run (task-1311, QA B3).
@@ -4113,7 +4313,7 @@ export function interactive(state, io, depth, args, proc = process) {
                     maybeSpeakVoiceAnswer(session); // task-1282: speak a voice-initiated answer when it settles
                     scheduleDraw();
                 };
-                const session = new AnalystSession({ skill: p.skill, mint: p.mint, symbol: p.symbol, screenState: buildScreenState(state), model: p.model, onAction }, onChange);
+                const session = new AnalystSession({ skill: p.skill, mint: p.mint, symbol: p.symbol, screenState: buildScreenState(state), model: p.model, onAction, ...(state.analystEngine === 'codex' ? { engine: 'codex' } : {}) }, onChange);
                 if (p.question)
                     session.ask(p.question, buildScreenState(state));
                 else
@@ -4151,6 +4351,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 scan.blocked.push(type);
                 if (scan.blocked.length > 6)
                     scan.blocked.shift();
+                scanLog(scan, Date.now(), 'blocked', scan.engine.lock?.symbol ?? '', `blocked analyst action "${type}" · observe-only`);
             }
             scanSay(`AI scan blocked analyst action "${type}" · observe-only (${error})`, 'warn', 5);
             scheduleDraw();
@@ -4182,6 +4383,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 state.aiFocused = false;
                 state.aiScroll = 0;
                 state.aiRevealAll = false;
+                scanLog(scan, Date.now(), 'lock', d.symbol, `locked · score ${d.score} · ${d.hits.map((h) => h.reason).join(' · ')}`);
                 startScanSession(d.mint, d.symbol, d.question, `AI scan · score ${d.score} · ${d.hits.map((h) => h.id).join(' + ')} → short read`);
                 syncAnalyst(state);
                 live.syncFastSet();
@@ -4199,6 +4401,7 @@ export function interactive(state, io, depth, args, proc = process) {
             const sess = scan.session;
             if (!sess)
                 return;
+            scanLog(scan, Date.now(), 'refresh', d.symbol, `moved: ${d.moved.join(', ')} · refreshing the read`);
             sess.ask(d.question, scanScreenState(state, d.mint, d.symbol), `AI scan refresh · ${d.moved.join(' · ')}`);
             if (state.analyst === sess) {
                 state.aiScroll = 0;
@@ -4237,7 +4440,8 @@ export function interactive(state, io, depth, args, proc = process) {
                 return;
             if (scan.session?.busy)
                 scan.session.interrupt();
-            scan.engine.cancelAnalysis(Date.now());
+            if (scan.engine.cancelAnalysis(Date.now()))
+                scanLog(scan, Date.now(), 'cancel', scan.engine.lock?.symbol ?? '', 'analysis cancelled by you · coin held, nothing else locks');
             if (live)
                 live.scanMeter = scanMeterOf(scan.engine, Date.now());
             scanSay(`analysis cancelled · scan holds $${cleanText(scan.engine.lock?.symbol ?? '', 12)} · R resume scan · Z stop`, 'ai', 5);
@@ -4323,6 +4527,10 @@ export function interactive(state, io, depth, args, proc = process) {
                         solUsd: () => state.sol?.price ?? live.positions.solUsd(),
                         imagePath: (v) => popupImagePath(state, v.image),
                         priceMode: () => priceModeOf(state), // task-1366
+                        chartAxis: () => chartAxisOf(state), // task-1472: the popup's Y axis
+                        setChartAxis: (a) => { say(setChartAxis(state, a), 'info', 3); if (!done)
+                            draw(); }, // task-1472: the popup's MCAP | PRICE control
+                        pnlChip: () => pnlChipFor(state, state.agentHud?.clock() ?? Date.now()), // task-1473 r2: the chip on the chart popup
                     } : null,
                 });
             }
@@ -5037,6 +5245,7 @@ export function interactive(state, io, depth, args, proc = process) {
             if (timer)
                 clearInterval(timer);
             void followSession?.stop();
+            agentPaper?.stop();
             guard.restore();
             guard.uninstall();
             cancelAllAnalysts();
@@ -5635,6 +5844,14 @@ export function interactive(state, io, depth, args, proc = process) {
                             draw();
                             continue;
                         }
+                        // 0.1.5: `/engine [auto|claude|codex]` switches the analyst CLI for new conversations; never sent to a model.
+                        const en0 = q.startsWith('/') ? parseEngineCommand(q) : null;
+                        if (en0) {
+                            state.aiInput = '';
+                            say(engineCommand(state, en0, io.env), typeof en0 === 'object' && 'error' in en0 ? 'warn' : 'info', 6);
+                            draw();
+                            continue;
+                        }
                         // task-1324: `/scan …` in the chat input is a command, never sent to claude.
                         const sc0 = q.startsWith('/') ? parseScanCommand(q) : null;
                         if (sc0) {
@@ -6085,6 +6302,36 @@ export function interactive(state, io, depth, args, proc = process) {
                     }
                     // market → rain: EMA on activity every tick, mood from the data every 4 s unless an event holds it
                     blendActivity(v, activityFor(state), v.frame % (tickEvery * 8) === 0 && v.frame >= moodHoldUntil);
+                    // task-1466: the agent's open PAPER position is marked with this terminal's own live price (the HUD's PnL).
+                    // Only a NEW price marks (a 10 s-old view price must not overwrite a fresher one a tool result carried).
+                    if (followSession && state.live && state.live.heldMint !== followSession.story.heldMint) {
+                        state.live.heldMint = followSession.story.heldMint;
+                        state.live.syncFastSet();
+                    } // task-1473
+                    if (followSession) {
+                        const held = followSession.story.heldMint;
+                        const px = held ? markPriceFor(state, held) : null;
+                        if (held && px !== null && px !== lastHudMark) {
+                            followSession.story.mark(held, px, Date.now());
+                            lastHudMark = px;
+                        }
+                    }
+                    // task-1473 r2: AI scan mode + the user's OWN held position → the PnL chip (band row, dock, chart popup)
+                    if (state.scan?.engine.on && state.live) {
+                        state.ownPnl ??= new OwnPnlTracker();
+                        state.ownPnl.update(ownHeldSample(state, Date.now()), Date.now());
+                        if (!followSession && state.live.heldMint !== state.ownPnl.mint) {
+                            state.live.heldMint = state.ownPnl.mint;
+                            state.live.syncFastSet();
+                        } // run25: pin it
+                    }
+                    else if (state.ownPnl?.mint) {
+                        state.ownPnl.update(null, 0);
+                        if (!followSession && state.live?.heldMint) {
+                            state.live.heldMint = null;
+                            state.live.syncFastSet();
+                        }
+                    }
                 }
                 if (state.ai && state.ai.phase === 'thinking') {
                     state.ai.ticks += 1;
@@ -6114,6 +6361,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 aiLive: !!(state.ai && state.ai.phase !== 'done'),
                 awake: v.frame < wakeUntil,
                 fxBusy: fxBusy(v),
+                hud: followSession !== null && hudAnimating(followSession.story.view(Date.now()), Date.now()),
                 frame: v.frame,
                 idleEvery,
             }))