dexterm-cli 0.1.3 → 0.1.5

package/dist/packages/data/src/trade/agent/paper-desk.js

@@ -0,0 +1,336 @@
+// task-1443 — the PAPER AGENT DESK: the one surface an untrusted agent (Claude Code, a custom bot) uses to
+// open, size, confirm and close a PAPER position, and to read paper positions and paper PnL — strictly inside
+// a user-armed mandate's caps (SPEC §6.13, ROADMAP Pillar 4: "agents are untrusted and can never arm, sign or
+// raise caps").
+//
+// Hard boundaries this module keeps, which the public claim "no MCP tool can sign or send" rests on:
+//   (a) PAPER LEDGER ONLY. The only trade op is `executor.execute`, a `TradeExecutor` whose `kind` MUST be
+//       'paper' (asserted at construction). This file imports NOTHING from the signer, the live executor, the
+//       swap BUILD adapter, the rpc sender or the bridge — only the paper ledger (./paper.ts), the mandate
+//       SCHEMA (../plans/mandate.ts), the audit journal, the panic kill-switch and the keyless quote TYPE. It
+//       is therefore structurally unable to reach any live / wallet / signer / send path (enforced by the
+//       no-sign registry test, task-1443).
+//   (b) CAPS COME FROM THE USER-SET MANDATE. Every limit is read from the armed `Mandate`, RE-READ on every
+//       call (in production: replayed from the hash-chained plans journal the app arms it in, so a revoke or a
+//       panic in the app halts the agent at once); there is NO method that changes a cap. An agent runs at the most-restricted confirmation tier (`AGENT_TIER`), so
+//       its per-trade cap is the mandate's per-trade cap times that tier's multiplier — it can never meet or
+//       exceed a human keypress tier.
+//   (c) EVERY CALL IS VALIDATED, JOURNALED AND HALTABLE. Before any state change the desk re-reads the control
+//       surface (pause / take-over / stop) and the panic file and re-checks the mandate is alive; a refusal is
+//       journaled too, so the spectator view and the audit log see it. The user always wins.
+import { systemClock } from "../../clock.js";
+import { mandateAlive, TIERS } from "../plans/mandate.js";
+import { KillSwitch } from "../kill-switch.js";
+import { capsHash } from "../plans/mandate.js";
+import { SOL_MINT, buildQuoteRequest, lamportsToSol, solToLamports, rawToTokens, } from "../../paper.js";
+/** The confirmation tier an agent is pinned to: the weakest, so an agent can never match a human keypress. */
+export const AGENT_TIER = 'hands-free';
+/** A refusal from the desk. `reason` is a stable code; `message` is human text (both are journaled). */
+export class PaperDeskError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'PaperDeskError';
+        this.reason = reason;
+    }
+}
+const isFiniteNum = (x) => typeof x === 'number' && Number.isFinite(x);
+/**
+ * The paper agent desk. One instance per armed mandate + paper wallet. All four verbs (open / size / confirm /
+ * close) and both reads (positions / pnl) run here; nothing else is exposed, and there is no cap setter.
+ */
+export class PaperAgentDesk {
+    mandateSrc;
+    /** The mandate the current call runs under (set by `gate`, which every mutating call runs first). */
+    mandate;
+    wallet;
+    executor;
+    quote;
+    solUsd;
+    control;
+    journal;
+    kill;
+    clock;
+    agent;
+    tickets = new Map();
+    ticketSeq = 0;
+    constructor(deps) {
+        if (deps.executor.kind !== 'paper') {
+            // The one invariant that makes the "no MCP tool can sign or send" claim true: the desk refuses to hold a
+            // live executor. There is no code path from here to a signer, so a live executor is a programming error.
+            throw new PaperDeskError('not-paper', `the paper agent desk only accepts a paper executor, got "${deps.executor.kind}"`);
+        }
+        const m = deps.mandate;
+        this.mandateSrc = typeof m === 'function' ? m : () => m;
+        this.wallet = deps.wallet;
+        this.executor = deps.executor;
+        this.quote = deps.quote;
+        this.solUsd = deps.solUsd;
+        this.control = deps.control;
+        this.journal = deps.journal;
+        this.kill = deps.killSwitch ?? new KillSwitch();
+        this.clock = deps.clock ?? systemClock;
+        this.agent = deps.agent ?? 'mcp-agent';
+    }
+    /** The agent's effective per-trade cap: the mandate cap times the weakest-tier multiplier. */
+    perTradeCapUsd() {
+        return this.mandate.budget.perTradeUsd * TIERS[AGENT_TIER].perTradeMultiplier;
+    }
+    /** Journal one audit event (kept out of the hot path's failure mode: never throws). */
+    note(type, data) {
+        try {
+            this.journal.append(type, { mandateId: this.mandate?.id ?? null, data: { agent: this.agent, ...data } });
+        }
+        catch { /* audit is best-effort */ }
+    }
+    /** Refuse (journaling the refusal) — the one place a PaperDeskError is raised for a gate failure. */
+    refuse(stage, reason, message, extra = {}) {
+        this.note('agent.paper.refused', { stage, reason, message, ...extra });
+        throw new PaperDeskError(reason, message);
+    }
+    /**
+     * The gate every mutating call runs first: panic file → control surface → mandate alive. A failure here is
+     * journaled and throws, so a paused / taken-over / stopped session (or a dead mandate) halts the agent.
+     */
+    gate(stage, extra = {}) {
+        const panic = this.kill.engaged();
+        if (panic)
+            this.refuse(stage, 'panic', `trading is halted (panic): ${panic.reason}`, extra);
+        const c = this.control();
+        if (c.state !== 'running') {
+            const msg = c.state === 'takeover' ? 'the user has taken over — agent paper trading is paused'
+                : c.state === 'paused' ? `agent paper trading is paused${c.reason ? `: ${c.reason}` : ''}`
+                    : `agent paper trading is stopped${c.reason ? `: ${c.reason}` : ''}`;
+            this.refuse(stage, c.state, msg, extra);
+        }
+        const m = this.mandateSrc();
+        if (!m)
+            this.refuse(stage, 'no-mandate', 'no armed mandate is available for agent paper trading', extra);
+        this.mandate = m;
+        const alive = mandateAlive(this.mandate, this.clock.now());
+        if (!alive.ok)
+            this.refuse(stage, alive.reason, `the mandate is not usable (${alive.reason})`, extra);
+    }
+    requireAction(stage, side, extra = {}) {
+        if (!this.mandate.allowed.actions.includes(side)) {
+            this.refuse(stage, 'action-not-allowed', `${side} is not permitted by the mandate`, extra);
+        }
+    }
+    requireMintAllowed(stage, mint, extra = {}) {
+        if (this.mandate.allowed.mints && !this.mandate.allowed.mints.includes(mint)) {
+            this.refuse(stage, 'mint-not-allowed', 'this mint is not on the mandate allow-list', extra);
+        }
+    }
+    price(stage, extra = {}) {
+        const p = this.solUsd();
+        if (!isFiniteNum(p) || p <= 0)
+            this.refuse(stage, 'no-usd-price', 'no fresh SOL/USD price — cannot price the mandate caps', extra);
+        return p;
+    }
+    // ── USD exposure derived from the paper wallet (source of truth), so caps survive a restart ──
+    costUsd(pos, solUsd) {
+        return pos ? lamportsToSol(pos.costLamports) * solUsd : 0;
+    }
+    openCostUsd(solUsd) {
+        return this.wallet.positions().reduce((s, p) => s + lamportsToSol(p.costLamports) * solUsd, 0);
+    }
+    /** Realized LOSS (USD, positive) booked since the mandate was armed. Over the whole paper wallet. */
+    realizedLossUsd(solUsd) {
+        const since = this.mandate.armedAt ?? this.mandate.createdAt;
+        let lamports = 0n;
+        for (const t of this.wallet.trades(1000)) {
+            if (t.t < since)
+                continue;
+            if (t.realizedLamports < 0n)
+                lamports += -t.realizedLamports;
+        }
+        return lamportsToSol(lamports) * solUsd;
+    }
+    /** Check the buy caps for `usd`, throwing a cap-named refusal on any breach. */
+    admitBuy(stage, mint, usd, solUsd, extra) {
+        const perTrade = this.perTradeCapUsd();
+        if (usd > perTrade + 1e-9)
+            this.refuse(stage, 'per-trade-cap', `$${usd.toFixed(2)} exceeds the agent per-trade cap $${perTrade.toFixed(2)}`, extra);
+        const coin = this.costUsd(this.wallet.position(mint), solUsd);
+        if (coin + usd > this.mandate.budget.perCoinUsd + 1e-9) {
+            this.refuse(stage, 'per-coin-cap', `$${(coin + usd).toFixed(2)} on this coin exceeds the per-coin cap $${this.mandate.budget.perCoinUsd.toFixed(2)}`, extra);
+        }
+        const total = this.openCostUsd(solUsd);
+        if (total + usd > this.mandate.budget.totalUsd + 1e-9) {
+            this.refuse(stage, 'total-cap', `$${(total + usd).toFixed(2)} deployed exceeds the total budget $${this.mandate.budget.totalUsd.toFixed(2)}`, extra);
+        }
+        const held = this.wallet.positions().filter((p) => p.tokensRaw > 0n);
+        if (!held.some((p) => p.mint === mint) && held.length >= this.mandate.limits.maxOpenPositions) {
+            this.refuse(stage, 'open-positions-cap', `${held.length} open paper positions reached the mandate limit ${this.mandate.limits.maxOpenPositions}`, extra);
+        }
+        const loss = this.realizedLossUsd(solUsd);
+        if (loss >= this.mandate.budget.dailyLossUsd - 1e-9) {
+            this.refuse(stage, 'daily-loss-limit', `realized loss $${loss.toFixed(2)} has reached the daily loss limit $${this.mandate.budget.dailyLossUsd.toFixed(2)}; no new buys`, extra);
+        }
+    }
+    // ───────────────────────────── the four verbs ─────────────────────────────
+    /** Open an inert PAPER ticket for a mint + side. Validates the gate, the action and the allow-list only. */
+    open(input) {
+        const side = input.side;
+        this.gate('open', { mint: input.mint, side });
+        if (typeof input.mint !== 'string' || input.mint.length < 32)
+            this.refuse('open', 'bad-request', 'a base58 mint is required');
+        if (!isFiniteNum(input.decimals) || input.decimals < 0 || input.decimals > 18)
+            this.refuse('open', 'bad-request', 'token decimals (0..18) are required');
+        this.requireAction('open', side, { mint: input.mint });
+        this.requireMintAllowed('open', input.mint, { side });
+        const t = {
+            id: `pt_${++this.ticketSeq}_${this.clock.now().toString(36)}`,
+            mint: input.mint, symbol: input.symbol, decimals: input.decimals, side, usd: null, fraction: null, openedAt: this.clock.now(),
+        };
+        this.tickets.set(t.id, t);
+        this.note('agent.paper.open', { ticketId: t.id, mint: t.mint, symbol: t.symbol, side });
+        return { ...t };
+    }
+    /** Size a ticket. Buy: `usd` (checked against the caps, never raised). Sell: `fraction` in (0, 1]. */
+    size(ticketId, input) {
+        const t = this.tickets.get(ticketId);
+        if (!t)
+            this.refuse('size', 'unknown-ticket', 'no such open ticket');
+        this.gate('size', { ticketId });
+        if (t.side === 'buy') {
+            const usd = input.usd;
+            if (!isFiniteNum(usd) || usd <= 0)
+                this.refuse('size', 'bad-request', 'a positive USD size is required for a buy', { ticketId });
+            const solUsd = this.price('size', { ticketId });
+            this.admitBuy('size', t.mint, usd, solUsd, { ticketId });
+            t.usd = usd;
+            t.fraction = null;
+        }
+        else {
+            const frac = input.fraction;
+            if (!isFiniteNum(frac) || !(frac > 0 && frac <= 1))
+                this.refuse('size', 'bad-request', 'a sell fraction in (0, 1] is required', { ticketId });
+            t.fraction = frac;
+            t.usd = null;
+        }
+        this.note('agent.paper.size', { ticketId, side: t.side, usd: t.usd, fraction: t.fraction });
+        return { ...t };
+    }
+    /** Confirm a sized ticket: re-check the gate and the caps, fetch a FRESH quote, book the PAPER fill. */
+    async confirm(ticketId) {
+        const t = this.tickets.get(ticketId);
+        if (!t)
+            this.refuse('confirm', 'unknown-ticket', 'no such open ticket');
+        this.gate('confirm', { ticketId });
+        this.requireAction('confirm', t.side, { ticketId });
+        this.requireMintAllowed('confirm', t.mint, { ticketId });
+        const order = await this.buildOrder('confirm', t);
+        const rec = await this.book('confirm', order, { ticketId });
+        this.tickets.delete(ticketId);
+        return { fill: rec, position: this.positionView(this.wallet.position(t.mint)) };
+    }
+    /** Close a fraction of a held PAPER position in one call (open sell → size fraction → confirm). */
+    async close(input) {
+        this.gate('close', { mint: input.mint });
+        this.requireAction('close', 'sell', { mint: input.mint });
+        this.requireMintAllowed('close', input.mint, {});
+        const pos = this.wallet.position(input.mint);
+        if (!pos || pos.tokensRaw <= 0n)
+            this.refuse('close', 'no-position', 'no open paper position in this mint to close', { mint: input.mint });
+        const fraction = input.fraction ?? 1;
+        if (!isFiniteNum(fraction) || !(fraction > 0 && fraction <= 1))
+            this.refuse('close', 'bad-request', 'fraction must be in (0, 1]', { mint: input.mint });
+        const t = { id: `pt_close_${++this.ticketSeq}`, mint: input.mint, symbol: pos.symbol, decimals: pos.decimals, side: 'sell', usd: null, fraction, openedAt: this.clock.now() };
+        this.note('agent.paper.close', { mint: input.mint, fraction });
+        const order = await this.buildOrder('close', t);
+        const rec = await this.book('close', order, { mint: input.mint });
+        return { fill: rec, position: this.positionView(this.wallet.position(input.mint)) };
+    }
+    /** Build the paper order from a ticket, re-checking the buy caps against the live wallet at execute time. */
+    async buildOrder(stage, t) {
+        if (t.side === 'buy') {
+            if (!isFiniteNum(t.usd) || t.usd <= 0)
+                this.refuse(stage, 'not-sized', 'the ticket has no size — call size first', { ticketId: t.id });
+            const solUsd = this.price(stage, { ticketId: t.id });
+            this.admitBuy(stage, t.mint, t.usd, solUsd, { ticketId: t.id });
+            const amountRaw = solToLamports(t.usd / solUsd);
+            if (amountRaw <= 0n)
+                this.refuse(stage, 'bad-request', 'the sized amount rounds to zero lamports', { ticketId: t.id });
+            return { mint: t.mint, symbol: t.symbol, side: 'buy', decimals: t.decimals, amountRaw, slippageBps: this.mandate.limits.maxSlippageBps };
+        }
+        const pos = this.wallet.position(t.mint);
+        if (!pos || pos.tokensRaw <= 0n)
+            this.refuse(stage, 'no-position', 'no paper tokens to sell', { ticketId: t.id });
+        const frac = t.fraction ?? 1;
+        let amountRaw = BigInt(Math.round(Number(pos.tokensRaw) * frac));
+        if (amountRaw > pos.tokensRaw)
+            amountRaw = pos.tokensRaw;
+        if (amountRaw <= 0n)
+            this.refuse(stage, 'bad-request', 'the sell fraction rounds to zero tokens', { ticketId: t.id });
+        return { mint: t.mint, symbol: pos.symbol, side: 'sell', decimals: pos.decimals, amountRaw, slippageBps: this.mandate.limits.maxSlippageBps };
+    }
+    /** Fetch a fresh quote and book the fill through the PAPER executor; journal the booked fill. */
+    async book(stage, order, extra) {
+        let quote;
+        try {
+            quote = await this.quote(buildQuoteRequest(order));
+        }
+        catch (e) {
+            this.refuse(stage, 'quote-failed', `could not price the trade: ${e instanceof Error ? e.message : String(e)}`, extra);
+        }
+        // Buys honour the mandate's price-impact ceiling (SwapQuote.priceImpactPct is already a PERCENT — the source
+        // converts Jupiter's 0..1 fraction once). Exits are never trapped by it, like the plan engine's stop leg.
+        if (order.side === 'buy' && isFiniteNum(quote.priceImpactPct) && quote.priceImpactPct > this.mandate.limits.maxPriceImpactPct + 1e-9) {
+            this.refuse(stage, 'price-impact', `price impact ${quote.priceImpactPct.toFixed(2)}% exceeds the mandate max ${this.mandate.limits.maxPriceImpactPct}%`, extra);
+        }
+        // The control surface may have flipped while the quote was in flight: re-check right before booking.
+        this.gate(stage, extra);
+        let rec;
+        try {
+            rec = await this.executor.execute(order, quote);
+        }
+        catch (e) {
+            this.refuse(stage, 'fill-failed', e instanceof Error ? e.message : String(e), extra);
+        }
+        this.note('agent.paper.fill', {
+            ...extra, mint: rec.mint, symbol: rec.symbol, side: rec.side, paper: true,
+            solDelta: rec.solDelta.toString(), tokenDelta: rec.tokenDelta.toString(),
+            priceSol: rec.priceSol, priceUsd: rec.priceUsd, realizedLamports: rec.realizedLamports.toString(), fillId: rec.id,
+        });
+        return rec;
+    }
+    // ───────────────────────────── the two reads ─────────────────────────────
+    positionView(pos) {
+        if (!pos)
+            return null;
+        const tokens = rawToTokens(pos.tokensRaw, pos.decimals);
+        const costSol = lamportsToSol(pos.costLamports);
+        return {
+            mint: pos.mint, symbol: pos.symbol, decimals: pos.decimals, tokens,
+            costSol, realizedSol: lamportsToSol(pos.realizedLamports),
+            avgEntrySol: tokens > 0 ? costSol / tokens : null,
+        };
+    }
+    /** Read paper positions (cost basis + realized; the caller may layer a live mark). Read-only. */
+    positions() {
+        return this.wallet.positions().map((p) => this.positionView(p)).filter(Boolean);
+    }
+    /** Read the paper PnL snapshot (balance, realized, open cost, per-position). Read-only, always PAPER. */
+    pnl() {
+        const s = this.wallet.summary();
+        const m = this.mandateSrc();
+        const positions = this.positions();
+        const realizedSol = positions.reduce((a, p) => a + p.realizedSol, 0);
+        const openCostSol = positions.reduce((a, p) => a + p.costSol, 0);
+        return {
+            paper: true,
+            balanceSol: lamportsToSol(s.balanceLamports),
+            startSol: lamportsToSol(s.startLamports),
+            realizedSol,
+            openCostSol,
+            positions,
+            mandate: m ? {
+                id: m.id, capsHash: capsHash(m), perTradeUsd: m.budget.perTradeUsd * TIERS[AGENT_TIER].perTradeMultiplier, perCoinUsd: m.budget.perCoinUsd,
+                totalUsd: m.budget.totalUsd, dailyLossUsd: m.budget.dailyLossUsd, maxOpenPositions: m.limits.maxOpenPositions,
+                maxPriceImpactPct: m.limits.maxPriceImpactPct, expiresAt: m.expiresAt,
+            } : null,
+        };
+    }
+}
+export { SOL_MINT };

package/dist/packages/data/src/trade/agent/rendezvous.js

@@ -0,0 +1,161 @@
+// task-1443 — the rendezvous a running dexterm writes so an EXTERNAL `dexterm mcp` server (spawned by the
+// user's own agent: Claude Code, Cursor, a custom bot) may paper-trade inside an armed mandate.
+//
+// Agent paper trading is OFF unless the user turns it on. When the user starts the app with the spectator
+// view open and names a mandate they ARMED by keypress (`--spectate-mcp --agent-paper <mandate-id>`), the app
+// writes `~/.dexterm/paper-agent.json` naming the shared paper wallet DB and the mandate ID — never the caps.
+// The MCP side REPLAYS that mandate from the hash-chained plans journal the app armed it in (verifying the
+// chain and the caps hash), so editing the rendezvous cannot raise a cap, and a revoke / panic in the app is
+// seen on the next call. A companion `~/.dexterm/paper-agent.control` carries the live control state (running /
+// paused / stopped / takeover), re-read on every mutating call. Agent calls journal to their OWN chain
+// (`paper-agent.journal`), so the app's plans journal keeps a single writer. All files are local and 0600;
+// nothing here is a key, a signer or a send path.
+import { readFileSync, writeFileSync, rmSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Journal } from "../plans/journal.js";
+import { capsHash } from "../plans/mandate.js";
+export const PAPER_AGENT_RENDEZVOUS = 'paper-agent.json';
+export const PAPER_AGENT_CONTROL = 'paper-agent.control';
+export const PAPER_AGENT_JOURNAL = 'paper-agent.journal';
+function home(env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export function paperAgentRendezvousPath(env = process.env) { return join(home(env), PAPER_AGENT_RENDEZVOUS); }
+export function paperAgentControlPath(env = process.env) { return join(home(env), PAPER_AGENT_CONTROL); }
+export function paperAgentJournalPath(env = process.env) { return join(home(env), PAPER_AGENT_JOURNAL); }
+/** The plans/mandate journal (same location as plans/service.ts `defaultPlansJournalPath`, which this module
+ *  deliberately does not import: the service graph reaches the live executor). Never taken from the rendezvous. */
+export function plansJournalPathFor(env = process.env) { return join(home(env), 'plans.journal'); }
+/** Turn agent paper trading ON: write the rendezvous (0600) and a `running` control state. */
+export function writePaperAgentRendezvous(rv, env = process.env) {
+    const p = paperAgentRendezvousPath(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    writeFileSync(p, JSON.stringify({ v: 2, db: rv.db, mandateId: rv.mandateId, ...(rv.agent ? { agent: rv.agent } : {}) }), { mode: 0o600 });
+    writeDeskControl({ state: 'running' }, env);
+}
+/** Turn it OFF: remove both files. Idempotent. */
+export function clearPaperAgentRendezvous(env = process.env) {
+    rmSync(paperAgentRendezvousPath(env), { force: true });
+    rmSync(paperAgentControlPath(env), { force: true });
+}
+/** Read the rendezvous, or null when agent paper trading is not enabled (or the file is malformed). Never throws. */
+export function readPaperAgentRendezvous(env = process.env) {
+    const p = paperAgentRendezvousPath(env);
+    if (!existsSync(p))
+        return null;
+    try {
+        const o = JSON.parse(readFileSync(p, 'utf8'));
+        if (!o || o.v !== 2 || typeof o.db !== 'string' || !o.db || typeof o.mandateId !== 'string' || !o.mandateId)
+            return null;
+        return { v: 2, db: o.db, mandateId: o.mandateId, ...(typeof o.agent === 'string' ? { agent: o.agent.slice(0, 40) } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+const VALID_STATES = ['running', 'paused', 'stopped', 'takeover'];
+/** Write the live control state (0600). The app calls this on pause / take-over / stop / resume. */
+export function writeDeskControl(control, env = process.env) {
+    const p = paperAgentControlPath(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    writeFileSync(p, JSON.stringify(control), { mode: 0o600 });
+}
+/**
+ * Read the control state, re-read on EVERY call (never cached), fail-closed:
+ *   - file absent         → stopped (the app writes `running` when it enables agent paper trading)
+ *   - a known state       → that state
+ *   - present but broken  → stopped
+ */
+export function readDeskControl(env = process.env) {
+    const p = paperAgentControlPath(env);
+    if (!existsSync(p))
+        return { state: 'stopped', reason: 'agent paper trading is not running in the app' };
+    try {
+        const o = JSON.parse(readFileSync(p, 'utf8'));
+        const state = typeof o.state === 'string' && VALID_STATES.includes(o.state) ? o.state : 'stopped';
+        return { state, reason: typeof o.reason === 'string' ? o.reason.slice(0, 200) : undefined };
+    }
+    catch {
+        return { state: 'stopped', reason: 'control file unreadable (treated as stopped)' };
+    }
+}
+/** Freshest mtime of a file (for mtime caches); 0 when absent. */
+export function fileMtimeMs(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+export function rendezvousMtimeMs(env = process.env) { return fileMtimeMs(paperAgentRendezvousPath(env)); }
+/**
+ * Replay ONE mandate from the hash-chained plans journal, read-only. Fails closed (null + reason) when the
+ * journal is absent, its chain does not verify, the mandate was never drafted, or the caps hash recorded at
+ * arming does not match the drafted caps. Status follows the journal: draft → armed → revoked/expired.
+ */
+export function loadMandateFromJournal(path, mandateId, clock) {
+    if (!existsSync(path))
+        return { mandate: null, reason: 'no plans journal (arm a mandate first)' };
+    let j;
+    try {
+        j = new Journal({ path, clock });
+    }
+    catch {
+        return { mandate: null, reason: 'plans journal unreadable' };
+    }
+    const v = j.verify();
+    if (!v.ok)
+        return { mandate: null, reason: `plans journal chain broken at seq ${v.atSeq} (${v.why})` };
+    let m = null;
+    for (const e of j.events) {
+        if (e.mandateId !== mandateId)
+            continue;
+        const d = (e.data ?? {});
+        if (e.type === 'mandate.draft') {
+            const drafted = structuredClone(d.mandate);
+            if (!drafted || drafted.id !== mandateId || capsHash(drafted) !== d.capsHash)
+                return { mandate: null, reason: 'mandate draft does not match its caps hash' };
+            m = drafted;
+        }
+        else if (e.type === 'mandate.armed' && m) {
+            if (d.capsHash !== capsHash(m))
+                return { mandate: null, reason: 'mandate armed with different caps than drafted' };
+            m.status = 'armed';
+            m.armedAt = d.armedAt;
+            m.armedBy = d.armedBy;
+        }
+        else if (e.type === 'mandate.revoked' && m) {
+            m.status = d.status ?? 'revoked';
+            m.revokedAt = e.ts;
+            m.revokedReason = d.reason ?? null;
+        }
+    }
+    if (!m)
+        return { mandate: null, reason: `no mandate ${mandateId} in the plans journal` };
+    Object.freeze(m.budget);
+    Object.freeze(m.limits);
+    Object.freeze(m.fees);
+    Object.freeze(m.allowed);
+    return { mandate: Object.freeze(m) };
+}
+/**
+ * A journal that may have several writers (one per `dexterm mcp` process): it re-loads the chain from disk
+ * before every append so each event links to the true head. Append-only, 0600 directory, same hash chain and
+ * `redact()` as the plans journal.
+ */
+export class SharedJournal {
+    path;
+    j;
+    constructor(path, clock) { this.path = path; this.j = new Journal({ path, clock }); }
+    append(type, fields = {}) {
+        if (existsSync(this.path))
+            this.j.load(this.path);
+        return this.j.append(type, fields);
+    }
+    verify() { if (existsSync(this.path))
+        this.j.load(this.path); return this.j.verify(); }
+    types() { if (existsSync(this.path))
+        this.j.load(this.path); return this.j.types(); }
+}

package/dist/packages/mcp/assets/kb/app-help/agent-paper-trade.md

@@ -0,0 +1,38 @@
+---
+id: agent-paper-trade
+title: Let an agent paper trade
+kind: app-help
+screen: all
+feature: mcp
+tags:
+  - app-help
+  - agent
+  - mcp
+  - paper
+  - autonomous
+  - experimental
+  - confirm
+  - close
+  - simulated
+flags:
+  - --agent-paper
+tools:
+  - paper_open_ticket
+  - paper_size_ticket
+  - paper_confirm
+  - paper_close
+  - paper_positions
+  - paper_pnl
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+Experimental, paper only, off by default. Arm a mandate yourself (its caps, by keypress), then start `dexterm --spectate-mcp --agent-paper <mandate-id>`: an agent connected through `dexterm mcp` can then open, size, confirm and close SIMULATED (paper) trades inside those caps with paper_open_ticket / paper_size_ticket / paper_confirm / paper_close, and read paper_positions / paper_pnl. The agent is untrusted: it can never sign, send a real transaction, touch keys, or raise a cap; its per-trade cap is a quarter of the mandate's, and a size over any cap is refused. Caps are re-read from your armed mandate on every call, so revoking it or the panic key stops the agent. Every call is journaled and shows in this terminal's agent activity; Ctrl+P pauses, Ctrl+K stops for the rest of the run, any key takes over, and quitting turns it off. Figures are simulated and are not a result.

package/dist/packages/mcp/assets/kb/app-help/ask-the-analyst.md

@@ -38,6 +38,6 @@ sources:
 date: 2026-10-16
 ---
 
-The analyst is your own `claude` login. ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.
+The analyst is your own `claude` login (or your own `codex` login: `/engine codex`, see "Run the analyst on Codex"). ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.
 
 Keys: `a`, `⏎` (screener).

package/dist/packages/mcp/assets/kb/app-help/connect-an-agent.md

@@ -34,6 +34,6 @@ sources:
 date: 2026-10-16
 ---
 
-`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.
+`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`, or set up Claude Code, Claude Desktop, Cursor or Codex in one command with `dexterm mcp install <client>`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.
 
 CLI: `dexterm mcp`.

package/dist/packages/mcp/assets/kb/app-help/dev-history.md

@@ -0,0 +1,32 @@
+---
+id: dev-history
+title: Check if a coin's creator rugged before (dev history)
+kind: app-help
+screen: token
+feature: token-intel
+tags:
+  - app-help
+  - dev
+  - deployer
+  - creator
+  - serial
+  - rugger
+  - rugged
+  - history
+  - launches
+tools:
+  - dev_history
+  - get_dev_history
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+The token screen's ON-CHAIN panel shows the creator's recorded track record (0.1.5): `Dev rugs (recorded)` (rugs out of labelled prior launches, with the sample n), `Dev launches seen`, `Dev sold its bag` (median minutes to the dev's exit) and `Dev linked` (funder or cluster from the wallet-intel scan). It comes from dexterm's own local history recorder (keyless creator links + code-only outcome labels), so it says `unknown` when there is no record; it is a risk flag from observed history, never a certificate. Alert on it with the rule field `devrugs`, e.g. `when devrugs >= 2 then alert(warn, "new coin from a wallet that rugged before") scope newpairs`. Agents and the analyst use the `dev_history` MCP tool.

package/dist/packages/mcp/assets/kb/app-help/paper-trade.md

@@ -31,6 +31,6 @@ sources:
 date: 2026-10-16
 ---
 
-Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The analyst can open a PAPER ticket but can never size, confirm or send it.
+Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The in-app analyst can open a PAPER ticket but can never size, confirm or send it. If you separately arm a mandate and enable agent paper trading, a connected agent can open, size, confirm and close PAPER trades inside your caps (never raising them, never signing) — see "Let an agent paper trade".
 
 Keys: `B` (token), `S` (token).

package/dist/packages/mcp/assets/kb/app-help/screen-positions.md

@@ -116,6 +116,9 @@ actions:
   - workspace.popups
   - workspace.default
   - screen.rules
+tools:
+  - paper_positions
+  - paper_pnl
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -127,7 +130,7 @@ sources:
 date: 2026-10-16
 ---
 
-Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow.
+Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow. An agent you enabled can read these over MCP with the read-only paper_positions and paper_pnl tools.
 
 Keys on this screen:
   `q/^C` — quit

package/dist/packages/mcp/assets/kb/app-help/screen-token.md

@@ -159,6 +159,7 @@ tools:
   - get_trades
   - get_candles
   - get_dev_history
+  - dev_history
   - rugcheck
 confidence: high
 owner: maintainers

package/dist/packages/mcp/assets/kb/app-help/spectate-an-agent.md

@@ -15,10 +15,13 @@ tags:
   - replay
   - stream
   - record
+  - mcp
+  - follow
 commands:
   - spectate
 flags:
   - --replay
+  - --spectate-mcp
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -31,6 +34,6 @@ sources:
 date: 2026-10-16
 ---
 
-`dexterm spectate --replay FILE` replays a saved agent session so you can watch what an agent did step by step; `dexterm spectate --info` shows the live read-only, token-gated, loopback spectator stream. The stream is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act.
+Watch an agent work. For an agent on the loopback bus, `dexterm agent serve --spectator-popup` opens the AGENT ACTIVITY window, `--spectate` starts the read-only, token-gated, loopback stream, and `--record FILE` saves a redacted session. For an agent connected over MCP (`dexterm mcp install`), run the app with `dexterm --spectate-mcp`: the running terminal then follows the agent — a navigation call moves the screen, a status line shows `agent <name>: opened <coin>`, ctrl+p pauses, ctrl+k stops and any key you press takes control. `dexterm spectate --replay FILE` replays a saved session step by step and `dexterm spectate --info` shows the live stream endpoint. Every shared copy is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act. Full docs: https://dexterm.xyz/docs/spectator/
 
 CLI: `dexterm spectate`.