dexterm-cli 0.1.2 → 0.1.4

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

@@ -19,14 +19,17 @@ import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { writeExport, exportViewFor } from "./export.js";
+import { openPnl, loadPnl, pnlKey } from "./pnl-app.js";
+import { shareCard, runLocal } from "./pnl-card.js";
 import { parseMintTarget, parseCoinTarget, resolveCoinTarget, isBareOpen } from "./coin-target.js";
 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, ImageService, encodePng, SummaryLimiter, buildSummaryWindow, KolStore, Cache, PackError, normalizeHandle, terminalSafe } from '../../data/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 { 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 { McpFollowSession } from "./mcp-follow.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";
@@ -39,6 +42,8 @@ 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";
 import { buildNotifier, hasPushChannel } from "./alerts/notifier.js";
+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 { resolveAnalystResults } from "./analyst/results.js";
@@ -57,7 +62,7 @@ import { FOLLOW_INPUT_MAX } from "./screens/follows.js";
 import { isPriceMode, configPriceMode, togglePriceMode, priceModeOf, planLevels } 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 } from '../../custom/src/index.js';
+import { DEFAULT_WORKSPACE, MORNING_HUD, applyAndJournal, policyCheck } from '../../custom/src/index.js';
 /**
  * Context the `screen_state` MCP tool returns AND the per-turn context block is rendered from
  * (task-1313): what the user is looking at right now — selected/hovered coin, screen, the visible
@@ -65,6 +70,37 @@ import { DEFAULT_WORKSPACE, MORNING_HUD, applyAndJournal } from '../../custom/sr
  * that bounds what the analyst's UI actions may reference. Token-derived text stays raw here; the
  * context-block renderer wraps it as untrusted before a model sees it.
  */
+/** Screens the analyst's `switch_screen` action may target (task-1413); the user-facing set. */
+export const SWITCHABLE_SCREENS = ['screener', 'token', 'newpairs', 'watchlist', 'analyst', 'positions', 'trending', 'kol'];
+/**
+ * A read-only snapshot of local UI state for the `app_state` MCP tool (task-1413): what the user sees.
+ * NEVER includes a secret — alert channels report a boolean "configured", computed from creds presence,
+ * never the token/webhook/key itself. `null` when there is no live config (one-shot fixture frames).
+ */
+export function appStateBlock(state) {
+    const ui = state.custom;
+    if (!ui)
+        return null;
+    const cfg = ui.config;
+    const home = ui.home;
+    const ch = (cfg.alerts?.channels ?? {});
+    const alerts = {
+        // toast is on unless explicitly disabled; the rest are off unless enabled. telegram/discord also need creds.
+        toast: ch.toast?.enabled !== false,
+        desktop: ch.desktop?.enabled === true,
+        telegram: ch.telegram?.enabled === true && readTelegramCreds(home) !== null,
+        discord: ch.discord?.enabled === true && readDiscordCreds(home) !== null,
+    };
+    return {
+        theme: state.theme.name,
+        priceMode: priceModeOf(state),
+        intensity: state.vfx.intensity,
+        calm: isCalm(state.vfx),
+        voice: { name: cfg.voice?.name ?? null, rate: cfg.voice?.rate ?? null },
+        scan: { on: state.scan?.engine.on ?? false },
+        alerts, // booleans only — never a token, webhook or key
+    };
+}
 export function buildScreenState(state) {
     const live = state.live;
     const sc = state.screener;
@@ -127,7 +163,14 @@ export function buildScreenState(state) {
         watchlist,
         ticket,
         positions,
-        actions: { enabled: !!live, mints: [...mints], feeds, sortKeys: SORT_KEYS.map((k) => k.key) },
+        actions: {
+            enabled: !!live, mints: [...mints], feeds, sortKeys: SORT_KEYS.map((k) => k.key),
+            // task-1413: targets the new tiered actions may reference.
+            screens: [...SWITCHABLE_SCREENS],
+            workspaces: Object.keys(state.custom?.config.layout?.workspaces ?? {}),
+            themes: themeNames(state.custom),
+        },
+        app: appStateBlock(state),
         now: Date.now(),
     };
 }
@@ -225,10 +268,12 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   dexterm wallet link|unlink|status|panic|resume  link a Phantom wallet via a local bridge (pubkey only); panic disables live trading, resume needs a TTY keypress
   dexterm plan propose|list|arm|cancel|journal     conditional order plans (entry/ladder/take-profit/moon bag/stop); arming needs a physical keypress
   dexterm mandate draft|list|arm|revoke            standing capped mandates (fast wallet); arming needs a physical keypress — voice/agents can never arm
-  dexterm follow add|remove|list|stats|trades|purge  copy trading tier 1: follow a wallet (your list, local labels), its decoded swaps + FIFO PnL; alerts in the app
-  dexterm mcp [install <client>|doctor]            read-only MCP server for your own agent; 'install' writes the config for claude-code|claude-desktop|cursor|codex|openclaw|generic (asks first, idempotent, backs up); 'doctor' verifies the connection
+  dexterm follow add|remove|list|stats|trades|mirror|purge  copy trading tier 1: follow a wallet (your list, local labels), its decoded swaps + FIFO PnL + win rate/early-entry; 'mirror' previews a one-key MIRROR TICKET from the wallet's latest buy (inert; arm in the app)
+  dexterm mcp [install <client>|doctor]            read-only MCP server for your own agent; 'install' writes the config for claude-code|claude-desktop|cursor|codex|generic (asks first, idempotent, backs up); 'doctor' verifies the connection
   dexterm alerts status|enable|disable|set-telegram|set-discord|test  where rule alerts are delivered (desktop / your Telegram / Discord; creds stay local, never logged)
   dexterm watch [--interval S] [--once] [--replay FILE]  run your rules headless and push alerts when the terminal is closed (no signer, proposals only)
+  dexterm record run|install|uninstall|status  keep the history recorder fed with no TUI open, as a user-level launchd agent (no network beyond the data layer; 'dexterm record help')
+  dexterm larp-detected --out DIR [--db PATH]  build timestamped high-risk follow-up drafts/cards from recorder history; never posts
   dexterm --fixtures                          interactive demo on seeded fixtures
   dexterm --screen <name>                     one-shot frame to stdout (live)
   dexterm --screen <name> --fixtures          one-shot frame from fixtures
@@ -241,6 +286,8 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   --sort KEY[:asc|desc]     ${SORT_KEYS.map((k) => k.key).join(' | ')}
   --preset NAME             ${PRESETS.map((p) => p.id).join(' | ')}
   --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)
   --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)
@@ -315,9 +362,10 @@ ${X_HELP}
   --version                 print the version
 
   Keys: 1-4 screens · tab cycle · j/k move · ⏎ open · esc back · a analyst · v voice · t theme · c calm · p pause · q quit
-        voice (JARVIS, macOS): v push-to-talk (press to talk, press to send) · m mute · , change voice · esc stop speaking
+        voice (JARVIS, macOS): v push-to-talk (press to talk, press to send) · m mute · , change voice · < / > slower/faster · esc stop speaking
                                voice asks the analyst or triggers safe actions (open/filter/watch/open a PAPER ticket);
                                a spoken "buy"/"sell" only OPENS a ticket — you still confirm it with a keypress
+                               spoken replies talk in market cap and round numbers (never a raw per-token price); < / > set the rate (saved to config)
         screener: / filter · s sort · [ ] presets · r refresh · g/G top/bottom
         social (task-1330): T trending in the space · K KOL lists · token screen: s social panel · f filter · x hidden spam
         dexterm kol list | create <name> | add <list> @handle | remove <list> @handle | mute @handle | unmute @handle | enable <list> | disable <list> | import <dir> | import-x
@@ -348,6 +396,7 @@ export function parseArgs(argv) {
         sound: false,
         trade: [], live: true,
         workspace: null, priceMode: null,
+        spectateMcp: false,
         help: false, version: false, unknown: [],
     };
     for (let i = 0; i < argv.length; i++) {
@@ -529,6 +578,9 @@ export function parseArgs(argv) {
                 throw new Error(`--price-mode expects price|mcap, got ${JSON.stringify(s.slice(0, 20))}`);
             a.priceMode = s;
         }
+        // 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 === '--workspace') {
             const s = str();
             if (!/^[a-z][a-z0-9-]{0,39}(\/[a-z][a-z0-9-]{0,39})?$/.test(s))
@@ -725,6 +777,12 @@ export async function main(argv, io = process, proc = process) {
         const { runAgent } = await import("./agent-cmd.js");
         return runAgent(argv.slice(1), io);
     }
+    // `dexterm spectate --replay FILE | --info` → watch an agent drive dexterm (task-1406, "watch the agent
+    // cook"): replay a saved session, or show the live read-only, token-gated, loopback spectator stream.
+    if (argv[0] === 'spectate') {
+        const { runSpectate } = await import("./spectate-cmd.js");
+        return runSpectate(argv.slice(1), io);
+    }
     // `dexterm recorder <cmd>` → the history recorder's tables: stats, label, prune, export (task-1329). No network.
     if (argv[0] === 'recorder') {
         const { recorderCli } = await import('../../recorder/src/index.js');
@@ -740,6 +798,11 @@ export async function main(argv, io = process, proc = process) {
         const { backtestCommand } = await import("./backtest-cmd.js");
         return backtestCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // Local-only marketing evidence pipeline (task-1433): drafts and cards for human review, never posts.
+    if (argv[0] === 'larp-detected') {
+        const { larpDetectedCommand } = await import("./larp-detected.js");
+        return larpDetectedCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm kol …` → KOL lists on the shared DB (task-1330): list/create/add/remove/mute/unmute/enable/disable/import.
     if (argv[0] === 'kol')
         return kolCommand(argv.slice(1), io);
@@ -760,6 +823,12 @@ export async function main(argv, io = process, proc = process) {
         const { kbSkillCommand } = await import("./kb-skill-cmd.js");
         return kbSkillCommand(argv[0], argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env, isTTY: io.stdout.isTTY === true });
     }
+    // `dexterm help [topic]` → the app-help KB (task-1413): how the app works, with the exact key/command.
+    // Backed by the same generated entries the analyst's `app_help` tool uses. No network, no model.
+    if (argv[0] === 'help') {
+        const { helpCommand } = await import("./help-cmd.js");
+        return helpCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr });
+    }
     // `dexterm theme list|show|init|check` → user themes under ~/.dexterm/themes (task-1358 Tier 2). No network.
     if (argv[0] === 'theme') {
         const { themeCommand } = await import("./theme-cmd.js");
@@ -792,6 +861,13 @@ export async function main(argv, io = process, proc = process) {
         const { watchCommand } = await import("./watch-cmd.js");
         return watchCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // `dexterm record [run|install|uninstall|status]` → the headless collector that keeps the history recorder
+    // fed with no TUI open (task-1414), to be driven by a user-level launchd LaunchAgent. No signer, no trading;
+    // requests honour the data layer limits / health gate / sweep budgets, and the Helius key is never printed.
+    if (argv[0] === 'record') {
+        const { recordCommand } = await import("./record-cmd.js");
+        return recordCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm pack list|verify|add|remove|export|lock|sign|trust|signers|keymap|widget` → shareable packs (task-1358 Tier 4):
     // plain files + sha256 lock + optional ssh signature. No network, no model; a pack never runs code (widgets land
     // disabled, unsigned rules load disabled, a keymap merges only on the explicit command).
@@ -1228,6 +1304,10 @@ function followsMove(state, delta) {
         return false;
     if (state.copyUi.input !== null || state.copyUi.mirror || state.copyUi.autoModal)
         return true;
+    if (state.copyUi.detail) {
+        state.copyUi.detail.scroll = Math.max(0, state.copyUi.detail.scroll + (delta > 0 ? 1 : -1));
+        return true;
+    } // task-1399: j/k scroll the detail view
     const n = state.copy?.follows().length ?? 0;
     if (n <= 0) {
         state.copyUi.selected = 0;
@@ -1513,6 +1593,10 @@ export function applyAction(state, action, stack) {
                 state.copyUi.notice = 'mirror preview closed';
                 break;
             } // task-1360: esc closes the mirror preview first
+            if (state.screen === 'follows' && state.copyUi?.detail) {
+                state.copyUi.detail = null;
+                break;
+            } // task-1399: esc closes the wallet detail view before leaving the screen
             const prev = stack.pop();
             if (prev)
                 state.screen = prev;
@@ -2337,6 +2421,10 @@ export function applyAction(state, action, stack) {
         case 'export.view':
             state.pendingExport = true;
             break;
+        // task-1407 PNL CARD: the loop opens the preview (recorded fills only) and runs the share keys.
+        case 'pnl.card':
+            state.pendingPnl = true;
+            break;
         case 'display.priceMode':
             state.pendingToast = togglePriceMode(state);
             break; // task-1366: display only, persisted
@@ -2708,6 +2796,12 @@ export function applyAnalystAction(state, raw, stack) {
     if (!res.ok)
         return { ok: false, error: res.error };
     const action = res.action;
+    // task-1413 tier (b): a persisted-config action is never applied by the model — return it as a PROPOSAL
+    // the user accepts with a keypress (applyAnalystConfig then journals it as actor 'analyst').
+    if (ACTION_TIER[action.type] === 'config') {
+        times.push(now);
+        return { ok: true, label: res.label, proposal: { action, summary: res.label } };
+    }
     // Resolve a mint to a row object from what is on screen (allow-list guarantees it was visible).
     const findSeed = (mint) => seedForMint(state, live, mint);
     const toScreen = (next) => { if (state.screen !== next) {
@@ -2747,6 +2841,10 @@ export function applyAnalystAction(state, raw, stack) {
         }
         case 'show_in_screener': {
             toScreen('screener');
+            if (action.preset && !setPreset(sc, action.preset))
+                return { ok: false, error: `preset "${action.preset}" is unavailable` };
+            if (action.preset && state.feed)
+                state.feed.setPreset(sc.preset);
             if (action.filter) {
                 const err = setFilter(sc, action.filter);
                 if (err)
@@ -2760,12 +2858,171 @@ export function applyAnalystAction(state, raw, stack) {
                     state.selected = i;
             }
             state.selected = clampSelection(sc, state.selected);
+            if (action.preset) {
+                times.push(now);
+                return { ok: true, label: res.label, refresh: true };
+            }
+            break;
+        }
+        // --- task-1413 view-only actions: applied immediately, shown as "analyst did X".
+        case 'switch_screen': {
+            toScreen(action.screen);
+            state.selected = 0;
+            break;
+        }
+        case 'switch_workspace': {
+            const r = switchWorkspace(state, action.name, stack);
+            if (!r.ok)
+                return { ok: false, error: r.reason };
+            times.push(now);
+            return { ok: true, label: res.label, refresh: r.refresh };
+        }
+        case 'chart_popup': {
+            // Open the chart popup (the loop performs the open/close); needs a selected coin to chart.
+            state.pendingPopup = action.open ? 'chart' : null;
+            break;
+        }
+        case 'toggle_calm': {
+            if (action.on) {
+                if (!isCalm(state.vfx)) {
+                    state.vfx.intensity = 'off';
+                    state.vfx.trail.clear();
+                }
+            }
+            else if (isCalm(state.vfx)) {
+                const back = 'fever';
+                state.vfx.intensity = back;
+                state.vfx.baseline = 0.12;
+            }
+            break;
+        }
+        case 'set_scan': {
+            scanCommand(state, action.on ? 'on' : 'off', stack);
+            break;
+        }
+        case 'export_view': {
+            state.pendingExport = true;
             break;
         }
     }
     times.push(now);
     return { ok: true, label: res.label };
 }
+/**
+ * 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
+ * screen/feed, set a filter, highlight a row, open the PAPER ticket editor. It never trades, sizes, confirms
+ * or signs, and the key loop flips control to the user before any of it runs, so the human always wins the
+ * screen. Unlike the analyst boundary it does not re-check the on-screen allow-list: the agent already made
+ * the call on its own server and this only reflects where it went. A no-op when live navigation is off.
+ */
+export function applyFollowNav(state, nav, stack) {
+    const sc = state.screener;
+    const live = state.live && state.screener.source !== 'fixtures' ? state.live : null;
+    const toScreen = (next) => { if (state.screen !== next) {
+        stack.push(state.screen);
+        state.screen = next;
+    } };
+    if (nav.mint && (!nav.screen || nav.screen === 'token')) {
+        if (!live)
+            return;
+        try {
+            live.openToken(seedForMint(state, live, nav.mint));
+            toScreen('token');
+        }
+        catch { /* a stale mint never breaks follow */ }
+        return;
+    }
+    if (nav.screen === 'ticket') {
+        if (!live || !nav.mint)
+            return;
+        try {
+            const seed = seedForMint(state, live, nav.mint);
+            live.openTicket({ mint: seed.mint, symbol: seed.symbol, name: seed.name }, nav.side === 'sell' ? 'sell' : 'buy');
+            toScreen('ticket');
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    if (nav.screen === 'watchlist') {
+        if (live && nav.mint) {
+            try {
+                if (!live.watch.has(nav.mint))
+                    live.watch.add(LiveContext.candidate(seedForMint(state, live, nav.mint)));
+            }
+            catch { /* ignore */ }
+        }
+        toScreen('watchlist');
+        return;
+    }
+    if (nav.feed || nav.filter || nav.highlight || nav.screen === 'screener') {
+        toScreen('screener');
+        if (nav.feed) {
+            if (setPreset(sc, nav.feed) && state.feed)
+                state.feed.setPreset(sc.preset);
+        }
+        if (nav.filter) {
+            try {
+                setFilter(sc, nav.filter);
+            }
+            catch { /* an invalid agent filter is ignored */ }
+        }
+        if (nav.highlight) {
+            const i = screenerView(sc).findIndex((r) => r.mint === nav.highlight);
+            if (i >= 0)
+                state.selected = i;
+        }
+        state.selected = clampSelection(sc, state.selected);
+        return;
+    }
+    if (nav.screen && isScreenKey(nav.screen))
+        toScreen(nav.screen);
+}
+/**
+ * task-1413: apply an accepted tier-(b) config proposal through the journaled path as actor `analyst`
+ * (so `ctrl+z` undoes it), creating the parent section when absent (exactly like the `$` / `,` handlers),
+ * then reflect it in the live UI where cheap. Throws on a refusal (schema / policy); the caller toasts it.
+ * Returns the one-line label for the confirmation toast.
+ */
+export function applyAnalystConfig(state, proposal) {
+    const ui = state.custom;
+    if (!ui)
+        throw new Error('config changes need a loaded config (not available on this run)');
+    const change = configChangeForAction(proposal.action);
+    if (!change)
+        throw new Error('not a persisted-config action');
+    const parent = ui.config[change.section];
+    const op = parent && typeof parent === 'object'
+        ? { op: 'add', path: change.path, value: change.value }
+        : { op: 'add', path: `/${change.section}`, value: { [change.key]: change.value } };
+    // THE GATE (task-1413 r2): re-run the model-actor policy on the exact journal op BEFORE writing. The
+    // analyst is not the user, so `DENIED_FOR_MODELS` applies — a config action can never reach a signer /
+    // trading / keys / caps / mandates / wallet / alerts / VOICE path, even behind the keypress confirm.
+    // CONFIG_ACTION_PATHS is already a closed non-denied allow-list; this is the server-side belt-and-braces.
+    const denied = policyCheck([op], 'claude');
+    if (denied.length)
+        throw new Error(`refused: ${denied.map((e) => e.msg).join('; ')}`);
+    const { config } = applyAndJournal(ui.home, [op], { actor: 'analyst', why: `analyst: ${proposal.summary}`, now: state.now.getTime() });
+    ui.config = config;
+    // Reflect the change in the running UI where it is cheap and local.
+    switch (proposal.action.type) {
+        case 'set_theme': {
+            const t = themeByName(ui, proposal.action.name);
+            if (t)
+                state.theme = t;
+            break;
+        }
+        case 'set_price_mode':
+            state.priceMode = proposal.action.mode;
+            break;
+        case 'set_intensity':
+            state.vfx.intensity = proposal.action.intensity;
+            state.vfx.baseline = proposal.action.intensity === 'fever' ? 0.12 : 0;
+            break;
+        default: break;
+    }
+    return proposal.summary;
+}
 /**
  * Route one decoded key: the screener's filter editor and sort menu swallow keys while open,
  * everything else goes through the keymap. Exported for tests.
@@ -2993,6 +3250,22 @@ export function applyKey(state, key, stack) {
             ui.input = cur + key.ch;
         return;
     }
+    // task-1399: on the follows screen (not typing, no modal), enter opens/closes the selected wallet's DETAIL view.
+    if (state.screen === 'follows' && state.copyUi && state.copyUi.input === null && !state.copyUi.mirror && !state.copyUi.autoModal && key.name === 'enter') {
+        const ui = state.copyUi;
+        if (ui.detail) {
+            ui.detail = null;
+            return;
+        }
+        const svc = state.copy;
+        const rows = svc?.follows() ?? [];
+        const f = rows[Math.max(0, Math.min(rows.length - 1, ui.selected))];
+        if (f)
+            ui.detail = { wallet: f.addr, scroll: 0 };
+        else
+            ui.notice = 'follow a wallet first (i)';
+        return;
+    }
     if (state.screen === 'kol' && state.kolInput !== null && state.kolInput !== undefined) {
         const kol = kolOf(state);
         if (key.name === 'esc') {
@@ -3540,6 +3813,9 @@ export function interactive(state, io, depth, args, proc = process) {
         let timer = null;
         let lastRefresh = 0;
         let done = false;
+        // 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;
         // 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
@@ -3569,7 +3845,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 }
             };
         const guard = terminalGuard(io, () => { done = true; prefetcher?.close(); if (timer)
-            clearInterval(timer); state.analyst?.cancel(); if (state.analystByMint)
+            clearInterval(timer); void followSession?.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() ?? '' });
         let lastTokenRefresh = 0;
@@ -3623,6 +3899,10 @@ export function interactive(state, io, depth, args, proc = process) {
         // Live bindings redraw as soon as something lands (one frame per macrotask at most).
         let drawPending = false;
         let lastFastDraw = 0;
+        // task-1399: a followed wallet's buy/sell also PUSHES through the alerts engine (desktop / Telegram / Discord)
+        // when the user enabled a push channel. Forward-declared; the real impl is set once the Notifier exists below.
+        // Read-only, like a rule alert — nothing here trades, arms or signs.
+        let pushCopyAlert = () => { };
         if (live) {
             // task-1360: poll the followed wallets for the whole run (live only; replay never spends credits) and toast
             // every new buy/sell a followed wallet made. Information only: no path from an alert to a trade exists here.
@@ -3635,6 +3915,8 @@ export function interactive(state, io, depth, args, proc = process) {
                         const a = as[as.length - 1];
                         const who = a.name ?? shortAddr(a.wallet);
                         say(`${who} ${a.trade.side === 'buy' ? 'BOUGHT' : 'SOLD'} ${shortAddr(a.trade.mint)}${a.trade.usd !== null ? ` ≈ $${a.trade.usd.toFixed(0)}` : ''}${a.lagMs !== null ? ` · lag ${Math.round(a.lagMs / 1000)}s` : ''}${as.length > 1 ? ` (+${as.length - 1} more · U)` : ' (U)'}`, a.trade.side === 'buy' ? 'up' : 'down', 6);
+                        for (const ca of as)
+                            pushCopyAlert(ca); // task-1399: push each one out through the alerts engine too
                     }
                 }
                 if (done || drawPending)
@@ -3734,6 +4016,37 @@ export function interactive(state, io, depth, args, proc = process) {
         // task-1326: an image landing (decoded, or found missing) repaints at most once per macrotask.
         if (images)
             images.onChange = () => scheduleDraw();
+        // task-1421: `--spectate-mcp` → follow an agent driving over MCP. The rendezvous lets a `dexterm mcp`
+        // server the external client spawned emit here; we tail it, move the terminal for navigation calls, and
+        // the owner's controls (ctrl+p pause/resume · ctrl+k stop · any key = take over) are handled in onInput.
+        // A read-only, loopback, token-gated stream opens too (`dexterm spectate --info`). Off (and zero-cost)
+        // unless the flag is set; nothing it folds can arm, sign, confirm, send or raise a cap.
+        if (args.spectateMcp) {
+            followSession = new McpFollowSession({
+                env: io.env,
+                stream: true,
+                onNav: (nav) => {
+                    const before = state.screen;
+                    try {
+                        applyFollowNav(state, nav, stack);
+                    }
+                    catch { /* a stale mint never breaks follow */ }
+                    if (state.screen !== before) {
+                        try {
+                            startTransition();
+                        }
+                        catch {
+                            transition = null;
+                        }
+                    }
+                    scheduleDraw();
+                },
+                onStatus: (line) => { say(line, 'ai', 4); scheduleDraw(); },
+                onEvent: () => scheduleDraw(),
+            });
+            void followSession.start();
+            say('following agents over MCP · ctrl+p pause · ctrl+k stop · any key takes over', 'ai', 6);
+        }
         // 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).
         const beginAnalyst = () => {
@@ -3755,6 +4068,15 @@ export function interactive(state, io, depth, args, proc = process) {
                 const r = applyAnalystAction(state, raw, stack);
                 if (!r.ok || !r.label)
                     return;
+                // task-1413 tier (b): a persisted-config request is a PROPOSAL — show it and wait for the user's key.
+                if (r.proposal) {
+                    // The proposal expires with its 8s toast (task-1413 defect c): a 'y' typed after it fades never
+                    // persists a stale change. `now` is the frame clock so it stays deterministic under replay.
+                    state.analystConfigProposal = { ...r.proposal, expiresAt: state.now.getTime() + 8000 };
+                    say(`analyst suggests: ${r.proposal.summary} — press y to accept, any other key to dismiss`, 'ai', 8);
+                    scheduleDraw();
+                    return;
+                }
                 const log = (state.analystActions ??= []);
                 log.push(r.label);
                 if (log.length > 6)
@@ -4232,6 +4554,10 @@ export function interactive(state, io, depth, args, proc = process) {
         const alertNotifier = state.custom && hasPushChannel(state.custom.config.alerts)
             ? buildNotifier(state.custom.home, state.custom.config.alerts, { toastSink: () => { } })
             : null;
+        // task-1399: now the Notifier exists, a followed wallet's buy/sell can be pushed. Fire-and-forget; a slow
+        // channel never blocks the loop; routing's `levels` filter lets the user scope (a buy is `up`, a sell `down`).
+        if (alertNotifier)
+            pushCopyAlert = (ca) => { void alertNotifier.deliver(copyAlertToDelivery(ca)).catch(() => { }); };
         const drainDeliveries = () => {
             const ui = state.rulesUi;
             if (!ui || !ui.pendingDeliveries.length)
@@ -4402,6 +4728,47 @@ export function interactive(state, io, depth, args, proc = process) {
                 return { price: np.price ?? null, mcap: np.mcap ?? null };
             return { price: null, mcap: null };
         };
+        // task-1411: a short instruction appended to a VOICE analyst question so the answer is built for the
+        // ear, not the screen — market cap not a per-token price, round numbers, short.
+        const VOICE_ANALYST_SPEECH_HINT = 'Answer out loud for text-to-speech: talk about price as market cap, never a raw per-token price; '
+            + 'round big numbers like "340 thousand" or "1.2 million"; no long addresses; keep it to two or three short sentences.';
+        // A spoken pronoun that points at the highlighted row ("this one", "this coin", "it").
+        const VOICE_SELECTION_PRONOUN = /\b(?:this (?:one|coin|token)|that (?:one|coin|token)|this|it)\b/i;
+        // A friendly, complete spoken ack for each navigable screen (the router's `say` is the terse key).
+        const NAV_ACK = {
+            screener: 'the screener', newpairs: 'new pairs', watchlist: 'your watchlist', analyst: 'the analyst', positions: 'your positions',
+        };
+        /**
+         * Run a VOICE-originated analyst question (task-1411). Fixes the screener silence: "what do you think
+         * of THIS ONE" aimed at a highlighted screener row used to start a context-free `trench-scan` with no
+         * mint, so the analyst never learned which coin "this one" was and answered with a short, useless
+         * fragment (the tester heard nothing useful). We now attach the SELECTED coin as a token-dossier target —
+         * exactly the context a token screen already gives — so it answers for real. The question also carries
+         * a short "answer for speech" instruction (market cap, round numbers, short).
+         */
+        const askVoiceAnalyst = (question) => {
+            const q = question.trim().slice(0, 400);
+            const instructed = `${q}\n\n${VOICE_ANALYST_SPEECH_HINT}`;
+            // A warm session: follow up on it so the model keeps context (the screen is already analyst/token).
+            if (state.analyst) {
+                state.analyst.ask(instructed, buildScreenState(state));
+                return;
+            }
+            const tv = live?.token?.view;
+            const sel = voiceSelected();
+            if (state.screen === 'token' && live && tv?.mint) {
+                state.pendingAnalyst = { skill: 'token-dossier', mint: tv.mint, symbol: tv.symbol, target: 'token', question: instructed };
+            }
+            else if (live && sel && VOICE_SELECTION_PRONOUN.test(q)) {
+                // the screener/analyst/watchlist/new-pairs highlighted coin IS "this one" (task-1411)
+                state.pendingAnalyst = { skill: 'token-dossier', mint: sel.mint, symbol: sel.symbol, target: 'analyst', question: instructed };
+            }
+            else {
+                state.pendingAnalyst = { skill: 'trench-scan', target: 'analyst', question: instructed };
+            }
+            if (state.pendingAnalyst)
+                beginAnalyst();
+        };
         /**
          * Perform a voice decision. Returns `false` when the app spoke its own reply (an ask / clarify), so
          * the controller does not read the decision's `say` line over it (task-1339, re-verify N1: the
@@ -4417,6 +4784,7 @@ export function interactive(state, io, depth, args, proc = process) {
                         const a = SCREEN_ACTION[d.screen];
                         if (a)
                             applyAction(state, a, stack);
+                        ask(NAV_ACK[d.screen] ?? d.say);
                         break;
                     }
                     case 'open-token': {
@@ -4541,14 +4909,14 @@ export function interactive(state, io, depth, args, proc = process) {
                     case 'analyst': {
                         // Route the question to the analyst, surface the chat, and let the answer be spoken when it lands.
                         // Capped like typed chat (400 chars): a runaway transcript never becomes a 200 KB argv (N7).
+                        // task-1411: askVoiceAnalyst attaches the highlighted coin as context so a screener "this one"
+                        // question is answered for real, and appends the "answer for speech" instruction.
                         if (state.screen !== 'token' && state.screen !== 'analyst') {
                             stack.push(state.screen);
                             state.screen = 'analyst';
                         }
                         syncAnalyst(state);
-                        sendChat(d.question.slice(0, 400));
-                        if (state.pendingAnalyst)
-                            beginAnalyst();
+                        askVoiceAnalyst(d.question);
                         break;
                     }
                     case 'workspace': {
@@ -4615,6 +4983,21 @@ export function interactive(state, io, depth, args, proc = process) {
             }
             catch { /* keep the voice for this run; nothing to surface */ }
         };
+        // task-1411: persist the < / > speaking-rate nudge to config.voice.rate (actor 'user', journaled →
+        // undo works). Best-effort: a failure keeps the rate for this run and never breaks the UI.
+        const persistVoiceRate = (rate) => {
+            const ui = state.custom;
+            if (!ui)
+                return;
+            try {
+                const op = ui.config.voice
+                    ? { op: 'add', path: '/voice/rate', value: rate }
+                    : { op: 'add', path: '/voice', value: { rate } };
+                const { config } = applyAndJournal(ui.home, [op], { actor: 'user', why: `voice rate ${rate}`, now: state.now.getTime() });
+                ui.config = config;
+            }
+            catch { /* keep the rate for this run; nothing to surface */ }
+        };
         const initVoice = async () => {
             if (voiceInitStarted)
                 return;
@@ -4643,6 +5026,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 } },
                 onDecision: handleVoiceDecision,
                 onVoiceChange: persistVoiceChoice,
+                onRateChange: persistVoiceRate,
             });
             voice.enable();
             await voice.toggleTalk(); // the first `v` press both enables and starts listening
@@ -4652,6 +5036,7 @@ export function interactive(state, io, depth, args, proc = process) {
             prefetcher?.close();
             if (timer)
                 clearInterval(timer);
+            void followSession?.stop();
             guard.restore();
             guard.uninstall();
             cancelAllAnalysts();
@@ -4706,6 +5091,56 @@ export function interactive(state, io, depth, args, proc = process) {
                     quit();
                     return;
                 }
+                // task-1421 follow-mode controls (only while following an MCP agent). ctrl+p pauses / resumes the
+                // terminal mirroring; ctrl+k stops following (removes the rendezvous so the server stops emitting);
+                // ANY other key while the agent is driving hands control to the user — the human and the agent never
+                // fight over the screen. The control keys are consumed; the take-over key still does its own job.
+                if (followSession) {
+                    if (key.ctrl && key.ch === 'k') {
+                        followSession.kill();
+                        draw();
+                        continue;
+                    }
+                    if (key.ctrl && key.ch === 'p') {
+                        if (followSession.isPaused)
+                            followSession.resume();
+                        else
+                            followSession.pause();
+                        draw();
+                        continue;
+                    }
+                    if (followSession.controlState === 'agent')
+                        followSession.userKey(); // take over, then fall through
+                }
+                // task-1413: a pending analyst config PROPOSAL owns the next key. `y` accepts and journals it as
+                // actor 'analyst' (ctrl+z undoes); any other key dismisses it. A stray key never persists a change.
+                // Two guards (defect c): the proposal does NOT steal a key while a TEXT INPUT is open — the GO-TO
+                // prompt or a focused analyst chat line — so a 'y' being typed goes into the field, not the accept;
+                // and an EXPIRED proposal (its 8s toast has faded) is silently dropped, never accepted by a late 'y'.
+                if (state.analystConfigProposal) {
+                    const inputOpen = !!state.goto || (state.aiFocused === true);
+                    const expired = state.now.getTime() >= state.analystConfigProposal.expiresAt;
+                    if (expired) {
+                        state.analystConfigProposal = null; // let the key fall through to its normal handler below
+                    }
+                    else if (!inputOpen) {
+                        const prop = state.analystConfigProposal;
+                        state.analystConfigProposal = null;
+                        if (key.ch === 'y' || key.ch === 'Y') {
+                            try {
+                                say(`analyst ${applyAnalystConfig(state, prop)} · ctrl+z undoes`, 'ai', 5);
+                            }
+                            catch (e) {
+                                say(`change refused: ${describeError(e)}`, 'warn', 4);
+                            }
+                        }
+                        else {
+                            say('dismissed the analyst change', 'ai', 3);
+                        }
+                        draw();
+                        continue;
+                    }
+                }
                 // task-1388 GO-TO prompt: while the "open any coin" input is open it owns the keyboard. Route the key
                 // straight to applyKey (which does the capture / open) and skip the voice, calm, demo and keymap
                 // handlers below — otherwise a base58 char like v / m / c would toggle voice or calm instead of typing.
@@ -4740,7 +5175,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 // `micEngaged` also covers the window while the mic is still OPENING (listen() in flight), so a key
                 // pressed before the engine came up closes the session the moment it arrives (task-1339, N3/N8).
                 if (voice?.micEngaged) {
-                    const isVoiceCtl = key.name === 'char' && !key.ctrl && !key.alt && (key.ch === 'v' || key.ch === 'm' || key.ch === ',');
+                    const isVoiceCtl = key.name === 'char' && !key.ctrl && !key.alt && (key.ch === 'v' || key.ch === 'm' || key.ch === ',' || key.ch === '<' || key.ch === '>');
                     if (key.name === 'esc') {
                         voice.cancelListen();
                         draw();
@@ -4782,6 +5217,16 @@ export function interactive(state, io, depth, args, proc = process) {
                             draw();
                             continue;
                         }
+                        if (voice?.isEnabled && key.ch === '<') {
+                            voice.nudgeRate(-1);
+                            draw();
+                            continue;
+                        } // slower (task-1411)
+                        if (voice?.isEnabled && key.ch === '>') {
+                            voice.nudgeRate(1);
+                            draw();
+                            continue;
+                        } // faster (task-1411)
                     }
                 }
                 // A modal overlay (welcome/help) is open: any key dismisses it; `?` switches welcome→help (task-1305).
@@ -4800,6 +5245,32 @@ export function interactive(state, io, depth, args, proc = process) {
                     draw();
                     continue;
                 }
+                // task-1407: the PnL card preview owns the keys while open (share / save / toggles / other coin / esc).
+                if (state.overlay === 'pnl' && state.pnl) {
+                    const ui = state.pnl;
+                    const eff = pnlKey(ui, key);
+                    if (eff.kind === 'close') {
+                        state.overlay = null;
+                        state.pnl = null;
+                    }
+                    else if (eff.kind === 'reload') {
+                        ui.stats = null;
+                        ui.error = null;
+                        void loadPnl(state).then(() => { if (!done)
+                            draw(); });
+                    }
+                    else if (eff.kind === 'share' && ui.stats) {
+                        ui.busy = true;
+                        ui.notice = null;
+                        void shareCard(ui.stats, { ...ui.opts }, eff.action, { platform: process.platform, env: io.env, run: runLocal, openUrl: (u) => openInBrowser(u), copyText: copyToClipboard })
+                            .then((r) => { ui.notice = r.message; say(r.message, 'info', 10); })
+                            .catch((e) => { ui.notice = `card failed: ${describeError(e)}`; })
+                            .finally(() => { ui.busy = false; if (!done)
+                            draw(); });
+                    }
+                    draw();
+                    continue;
+                }
                 // task-1358: the WORKSPACES card — a digit picks a slot, j/k move, ⏎ activates, esc/q/ctrl+w w close.
                 if (state.overlay === 'workspaces' && state.custom) {
                     const ui = state.custom;
@@ -5449,6 +5920,16 @@ export function interactive(state, io, depth, args, proc = process) {
                     say(`export failed: ${describeError(e)}`, 'warn', 6);
                 }
             }
+            if (state.pendingPnl) {
+                // task-1407: open the PnL card preview for this screen (recorded fills only), then build the card.
+                state.pendingPnl = false;
+                const why = openPnl(state);
+                if (why)
+                    say(why, 'warn', 6);
+                else
+                    void loadPnl(state).then(() => { if (!done)
+                        draw(); });
+            }
             if (state.pendingToast) {
                 // task-1315: surface the link list / "no link" reply as a durable toast. Drained BEFORE
                 // pendingOpen so that on a successful open the "opened <url>" toast overwrites the "open <url>" one.
@@ -5528,6 +6009,9 @@ export function interactive(state, io, depth, args, proc = process) {
                                 lastTokenRefresh = Date.now();
                                 void live.token.load();
                             }
+                            // task-1404: keep the open token's credit-metered holder/rug intel LIVE (slow cadence, budget-gated inside).
+                            if (state.screen === 'token' && live.token)
+                                live.refreshOpenIntel(Date.now());
                             if (state.screen === 'watchlist' && Date.now() - lastWatchRefresh >= WATCH_REFRESH_MS) {
                                 lastWatchRefresh = Date.now();
                                 void live.watch.refresh();