dexterm-cli 0.1.4 → 0.1.6

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

@@ -0,0 +1,401 @@
+// 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;
+    }
+}
+export const DEFAULT_QUOTE_RETRY = { maxAttempts: 4, maxWaitMs: 6_000, maxTotalMs: 25_000 };
+/** A keyless rate limit (a 429, or the data layer's own 429 cool-down / bucket pause), which is worth a bounded re-quote. */
+export function isRateLimitedQuoteError(e) {
+    if (!(e instanceof Error))
+        return false;
+    if (e.name === 'JupiterRateLimitedError')
+        return true;
+    if (e.name === 'SourceUnavailableError')
+        return /jupiter/.test(e.message);
+    return e.name === 'HttpError' && e.status === 429;
+}
+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;
+    quoteRetry;
+    onQuoteRetry;
+    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';
+        const r = deps.quoteRetry ?? DEFAULT_QUOTE_RETRY;
+        this.quoteRetry = { maxAttempts: Math.max(1, Math.floor(r.maxAttempts)), maxWaitMs: Math.max(0, r.maxWaitMs), maxTotalMs: Math.max(0, r.maxTotalMs) };
+        this.onQuoteRetry = deps.onQuoteRetry ?? null;
+    }
+    /** 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, quoteAttempts } = await this.book('confirm', order, { ticketId });
+        this.tickets.delete(ticketId);
+        return { fill: rec, position: this.positionView(this.wallet.position(t.mint)), quoteAttempts };
+    }
+    /** 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, quoteAttempts } = await this.book('close', order, { mint: input.mint });
+        return { fill: rec, position: this.positionView(this.wallet.position(input.mint)), quoteAttempts };
+    }
+    /** 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 for this call. A short rate limit is re-quoted inside the bounded `quoteRetry` budget:
+     * each retry is journaled and reported first, waits min(stated wait, maxWaitMs), then re-runs the gate, so a
+     * pause during the wait still halts the agent. Any other error, the last allowed attempt, or the spent budget
+     * (an attempt still in flight is aborted) refuses with the verbatim message. No quote outlives the call.
+     */
+    async freshQuote(stage, order, extra) {
+        const { maxAttempts, maxWaitMs, maxTotalMs } = this.quoteRetry;
+        const started = this.clock.now();
+        let lastRateLimit = null;
+        for (let attempt = 1;; attempt++) {
+            const budget = new AbortController();
+            const disarm = new AbortController();
+            void this.clock.sleep(Math.max(1, maxTotalMs - (this.clock.now() - started)), disarm.signal)
+                .then(() => { if (!disarm.signal.aborted)
+                budget.abort(); });
+            let quote = null;
+            let failure = null;
+            try {
+                quote = await this.quote(buildQuoteRequest(order), budget.signal);
+            }
+            catch (e) {
+                failure = e;
+            }
+            finally {
+                disarm.abort();
+            }
+            if (quote && !budget.signal.aborted)
+                return { quote, attempts: attempt };
+            const msg = failure instanceof Error ? failure.message : failure === null ? 'no quote' : String(failure);
+            const elapsed = this.clock.now() - started;
+            const tried = attempt > 1 ? ` (${attempt} quote attempts in ${Math.round(elapsed / 1000)}s)` : '';
+            if (budget.signal.aborted) {
+                this.refuse(stage, 'quote-failed', `could not price the trade within ${Math.round(maxTotalMs / 1000)}s${lastRateLimit ? `: ${lastRateLimit}` : ''}${tried}`, { ...extra, quoteAttempts: attempt });
+            }
+            if (!isRateLimitedQuoteError(failure))
+                this.refuse(stage, 'quote-failed', `could not price the trade: ${msg}${tried}`, { ...extra, quoteAttempts: attempt });
+            lastRateLimit = msg;
+            const stated = failure.retryAfterMs;
+            const wait = Math.min(maxWaitMs, Math.max(1_000, typeof stated === 'number' && Number.isFinite(stated) ? stated : 2_000 * attempt));
+            if (attempt >= maxAttempts || elapsed + wait >= maxTotalMs) {
+                this.refuse(stage, 'quote-failed', `could not price the trade: ${msg}${tried}`, { ...extra, quoteAttempts: attempt });
+            }
+            const info = { stage, mint: order.mint, side: order.side, attempt: attempt + 1, maxAttempts, waitMs: wait, message: msg };
+            this.note('agent.paper.quote-retry', { ...extra, ...info });
+            try {
+                this.onQuoteRetry?.(info);
+            }
+            catch { /* the spectator is best-effort */ }
+            await this.clock.sleep(wait);
+            this.gate(stage, extra);
+        }
+    }
+    /** Fetch a fresh quote and book the fill through the PAPER executor; journal the booked fill. */
+    async book(stage, order, extra) {
+        const { quote, attempts } = await this.freshQuote(stage, order, extra);
+        if (attempts > 1)
+            extra = { ...extra, quoteAttempts: attempts };
+        // 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: rec, quoteAttempts: attempts };
+    }
+    // ───────────────────────────── 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/data/src/trade/plans/engine.js

@@ -268,6 +268,8 @@ export class PlanEngine {
     authorizeCopy(mandateId, proof, wallet) {
         if (!this.gate.handsFreeAllowed())
             throw new PolicyRefusal('gate-on', 'copy automation needs the less-safe opt-in');
+        if (this.mandates.get(mandateId)?.m.paperOnly)
+            throw new PolicyRefusal('paper-only-mandate', 'a paper-only mandate is for the agent paper desk; copy automation cannot use it');
         this.armMandate(mandateId, proof);
         return (input, supply, ref) => {
             const check = () => {
@@ -315,6 +317,9 @@ export class PlanEngine {
         const alive = mandateAlive(x.m, this.clock.now());
         if (!alive.ok)
             refuse(alive.reason, 'mandate is not alive');
+        // task-1469: a paper-only mandate (PAPER_HARD ceilings) feeds the agent paper desk only; no plan arms into it.
+        if (x.m.paperOnly)
+            refuse('paper-only-mandate', 'a paper-only mandate is for the agent paper desk; plans cannot arm into it');
         if (TIERS[tier].rank > TIERS[x.m.maxTier].rank)
             refuse('tier-not-allowed', `this mandate accepts up to ${x.m.maxTier}; ${tier} is weaker`);
         const v = this.admit(r, x, tier);
@@ -599,6 +604,8 @@ export class PlanEngine {
         const alive = mandateAlive(m, now);
         if (!alive.ok)
             return no(alive.reason, 'mandate not alive');
+        if (m.paperOnly)
+            return no('paper-only-mandate', 'a paper-only mandate never fires a plan');
         if (now > p.expiresAt)
             return no('plan-expired', 'plan expired');
         if (!m.allowed.actions.includes(side))