dexterm-cli 0.1.5 → 0.1.7

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

@@ -18,11 +18,22 @@
 //   (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.
+//
+// task-1506 (AUTOTRADE AT-4, additive): the autotrade position monitor sells through `PaperExitDesk`, a subclass
+// at the end of this file, so the MCP desk's own surface is unchanged.
+//   P1  desk-side EXIT PLANS: an entry registers its exit plan (`agent.paper.exit.plan`), and every monitor sell
+//       is an `exit()` journaled as `agent.paper.exit.<rule>` (cost-recovery, bag-trail, tp1, stop, …) before
+//       its fill; a plan is done (`agent.paper.exit.done`) once the position is empty.
+//   P2  a `close-only` control state: sells (exits) still run, even on an expired or revoked mandate, while every
+//       buy is refused. A panic still halts everything.
+//   P4  a `note` on fills (who, which plan, the exit rule, the agent's own reason), journaled with the fill.
+// None of these raises a cap or adds a buy path: a note and a plan are journal data, an exit is a sell.
 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";
+import { buildFillTag, buildLateTag } from "../ledger/tags.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). */
@@ -34,7 +45,51 @@ export class PaperDeskError extends Error {
         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;
+}
+/** task-1530: most `tag` calls per minute (a journal-only call, but still bounded). */
+export const TAG_RATE_PER_MIN = 30;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9:_.-]{0,79}$/;
 const isFiniteNum = (x) => typeof x === 'number' && Number.isFinite(x);
+const NOTE_KEY = /^[A-Za-z][A-Za-z0-9_.-]{0,39}$/;
+export function sanitizeFillNote(note) {
+    if (typeof note === 'string') {
+        const s = note.slice(0, 400);
+        return s ? s : undefined;
+    }
+    if (!note || typeof note !== 'object' || Array.isArray(note))
+        return undefined;
+    const out = {};
+    let n = 0;
+    for (const [k, v] of Object.entries(note)) {
+        if (n >= 16)
+            break;
+        if (!NOTE_KEY.test(k))
+            continue;
+        if (typeof v === 'string')
+            out[k] = v.slice(0, 200);
+        else if (isFiniteNum(v) || typeof v === 'boolean' || v === null)
+            out[k] = v;
+        else
+            continue;
+        n++;
+    }
+    return n ? out : undefined;
+}
+/** Exit rule → journal slug (`time_review:no-answer` → `time-review-no-answer`). `plan` and `done` are reserved. */
+export function exitRuleSlug(rule) {
+    const s = String(rule).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+    return s && s !== 'plan' && s !== 'done' ? s : null;
+}
 /**
  * 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.
@@ -52,6 +107,10 @@ export class PaperAgentDesk {
     kill;
     clock;
     agent;
+    quoteRetry;
+    onQuoteRetry;
+    sessionSrc;
+    tagTimes = [];
     tickets = new Map();
     ticketSeq = 0;
     constructor(deps) {
@@ -71,6 +130,10 @@ export class PaperAgentDesk {
         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;
+        this.sessionSrc = deps.sessionId ?? (() => null);
     }
     /** The agent's effective per-trade cap: the mandate cap times the weakest-tier multiplier. */
     perTradeCapUsd() {
@@ -92,15 +155,18 @@ export class PaperAgentDesk {
      * 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 = {}) {
+    gate(stage, extra = {}, side) {
         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') {
+        // close-only (task-1506 P2): a sell passes the control surface and a dead mandate; a buy never does.
+        const exitOnly = c.state === 'close-only' && side === 'sell';
+        if (c.state !== 'running' && !exitOnly) {
             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}` : ''}`;
+                    : c.state === 'close-only' ? `agent paper trading is close-only${c.reason ? `: ${c.reason}` : ''}; exits run, new buys are refused`
+                        : `agent paper trading is stopped${c.reason ? `: ${c.reason}` : ''}`;
             this.refuse(stage, c.state, msg, extra);
         }
         const m = this.mandateSrc();
@@ -108,7 +174,7 @@ export class PaperAgentDesk {
             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)
+        if (!alive.ok && !exitOnly)
             this.refuse(stage, alive.reason, `the mandate is not usable (${alive.reason})`, extra);
     }
     requireAction(stage, side, extra = {}) {
@@ -172,7 +238,7 @@ export class PaperAgentDesk {
     /** 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 });
+        this.gate('open', { mint: input.mint, side }, 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)
@@ -192,7 +258,7 @@ export class PaperAgentDesk {
         const t = this.tickets.get(ticketId);
         if (!t)
             this.refuse('size', 'unknown-ticket', 'no such open ticket');
-        this.gate('size', { ticketId });
+        this.gate('size', { ticketId }, t.side);
         if (t.side === 'buy') {
             const usd = input.usd;
             if (!isFiniteNum(usd) || usd <= 0)
@@ -213,21 +279,22 @@ export class PaperAgentDesk {
         return { ...t };
     }
     /** Confirm a sized ticket: re-check the gate and the caps, fetch a FRESH quote, book the PAPER fill. */
-    async confirm(ticketId) {
+    async confirm(ticketId, opts = {}) {
         const t = this.tickets.get(ticketId);
         if (!t)
             this.refuse('confirm', 'unknown-ticket', 'no such open ticket');
-        this.gate('confirm', { ticketId });
+        this.gate('confirm', { ticketId }, t.side);
         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 });
+        const tag = buildFillTag(t.side, opts.tag);
+        const { rec, quoteAttempts } = await this.book('confirm', order, { ticketId }, sanitizeFillNote(opts.note), tag);
         this.tickets.delete(ticketId);
-        return { fill: rec, position: this.positionView(this.wallet.position(t.mint)) };
+        return { fill: rec, position: this.positionView(this.wallet.position(t.mint)), quoteAttempts, tag };
     }
     /** 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.gate('close', { mint: input.mint }, 'sell');
         this.requireAction('close', 'sell', { mint: input.mint });
         this.requireMintAllowed('close', input.mint, {});
         const pos = this.wallet.position(input.mint);
@@ -239,8 +306,9 @@ export class PaperAgentDesk {
         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)) };
+        const tag = buildFillTag('sell', input.tag);
+        const { rec, quoteAttempts } = await this.book('close', order, { mint: input.mint }, sanitizeFillNote(input.note), tag);
+        return { fill: rec, position: this.positionView(this.wallet.position(input.mint)), quoteAttempts, tag };
     }
     /** Build the paper order from a ticket, re-checking the buy caps against the live wallet at execute time. */
     async buildOrder(stage, t) {
@@ -265,22 +333,73 @@ export class PaperAgentDesk {
             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);
+    /**
+     * 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, order.side);
         }
+    }
+    /** Fetch a fresh quote and book the fill through the PAPER executor; journal the booked fill. */
+    async book(stage, order, extra, note, tag) {
+        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);
+        this.gate(stage, extra, order.side);
+        // task-1530: the book (cash + open cost) just before this fill, for the trade ledger's % of book
+        const bookLamports = this.bookLamports();
         let rec;
         try {
             rec = await this.executor.execute(order, quote);
@@ -292,8 +411,62 @@ export class PaperAgentDesk {
             ...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,
+            ...(note !== undefined ? { note } : {}),
+            // task-1530: the facts the unified trade ledger needs, journaled with the fill (older journals lack them; the
+            // ledger then joins them from the paper wallet's own table)
+            decimals: rec.decimals, feeLamports: rec.feeLamports.toString(), impactPct: rec.priceImpactPct, slippageBps: rec.slippageBps,
+            ...(bookLamports !== null ? { bookLamports: bookLamports.toString() } : {}),
+            ...(tag ? { tag } : {}),
+            ...(this.sessionId() ? { sessionId: this.sessionId() } : {}),
         });
-        return rec;
+        return { rec: rec, quoteAttempts: attempts };
+    }
+    /** The model session id the launcher named, if it is a plain id. */
+    sessionId() {
+        let s = null;
+        try {
+            s = this.sessionSrc();
+        }
+        catch {
+            s = null;
+        }
+        return typeof s === 'string' && SESSION_ID.test(s) ? s : null;
+    }
+    /** Paper cash + the cost basis of every open position, lamports (null when the wallet cannot be read). */
+    bookLamports() {
+        try {
+            return this.wallet.balance() + this.wallet.positions().reduce((a, p) => a + (p.tokensRaw > 0n ? p.costLamports : 0n), 0n);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * task-1530: declare a PROFILE, REPROFILE or EXIT for a coin this desk traded, apart from its fill (a REPROFILE,
+     * or a line that was not passed with the fill: journaled `agent.paper.tag`, which the trade ledger reads as a
+     * late declaration). Journal-only: it books nothing, moves no money and works while trading is paused or stopped
+     * (a reason can always be recorded). The coin must be one the paper wallet holds or has held.
+     */
+    tag(input) {
+        const now = this.clock.now();
+        this.tagTimes = this.tagTimes.filter((t) => now - t < 60_000);
+        if (this.tagTimes.length >= TAG_RATE_PER_MIN)
+            throw new PaperDeskError('rate-limited', `at most ${TAG_RATE_PER_MIN} tags a minute`);
+        if (typeof input.mint !== 'string' || !this.wallet.position(input.mint))
+            throw new PaperDeskError('no-position', 'tag a coin the paper wallet holds or has traded (pass its mint)');
+        const g = buildLateTag(input);
+        if (!g.ok)
+            throw new PaperDeskError('bad-request', g.why);
+        if (g.tagKind === 'reprofile') {
+            const pos = this.wallet.position(input.mint);
+            if (!pos || pos.tokensRaw <= 0n)
+                throw new PaperDeskError('no-position', 'a REPROFILE needs a position that is still held');
+        }
+        this.tagTimes.push(now);
+        const declared = g.tagKind === 'profile' ? { profile: g.profile, reason: g.reason }
+            : g.tagKind === 'reprofile' ? { from: g.from, to: g.to, reason: g.reason } : { exitReason: g.exitReason, reason: g.reason };
+        this.note('agent.paper.tag', { mint: input.mint, tagKind: g.tagKind, ...declared, ...(g.line ? { line: g.line } : {}), ...(this.sessionId() ? { sessionId: this.sessionId() } : {}) });
+        return { recorded: true, mint: input.mint, tagKind: g.tagKind, declared };
     }
     // ───────────────────────────── the two reads ─────────────────────────────
     positionView(pos) {
@@ -333,4 +506,108 @@ export class PaperAgentDesk {
         };
     }
 }
+/**
+ * task-1506 P1: the paper desk the autotrade monitor sells through. It is the same desk (every gate, cap, quote,
+ * journal and the paper executor), plus exit plans and rule-named exits. It is a separate class on purpose: the
+ * MCP paper tools hold a plain PaperAgentDesk, whose surface stays exactly the six reviewed verbs.
+ */
+export class PaperExitDesk extends PaperAgentDesk {
+    /** Exit plans by mint (one held position per mint in the paper wallet). */
+    plans = new Map();
+    async confirm(ticketId, opts = {}) {
+        const r = await super.confirm(ticketId, opts);
+        if (r.fill.side === 'sell')
+            this.planDoneIfEmpty(r.fill.mint, 'confirm');
+        return r;
+    }
+    async close(input) {
+        const r = await super.close(input);
+        this.planDoneIfEmpty(input.mint, 'close');
+        return r;
+    }
+    /**
+     * Register the exit plan for a held position (P1). Journal data only: it needs a held paper position and moves
+     * no money, so it runs in every control state (a restart re-registers its plans, journaled `restored: true`).
+     * Registering the same position again returns the existing plan.
+     */
+    registerExitPlan(input) {
+        const pos = this.wallet.position(input.mint);
+        if (!pos || pos.tokensRaw <= 0n)
+            this.refuse('exit-plan', 'no-position', 'no open paper position in this mint to plan exits for', { mint: input.mint });
+        const ok = (v, n) => typeof v === 'string' && v.length > 0 && v.length <= n;
+        if (!ok(input.owner, 40) || !ok(input.positionId, 80) || !ok(input.profileId, 64))
+            this.refuse('exit-plan', 'bad-request', 'an exit plan needs an owner, a position id and a profile id', { mint: input.mint });
+        const have = this.plans.get(input.mint);
+        if (have && have.positionId === input.positionId)
+            return { ...have };
+        const note = sanitizeFillNote(input.note);
+        const plan = {
+            planId: `xp_${++this.ticketSeq}_${this.clock.now().toString(36)}`, mint: input.mint, symbol: pos.symbol, owner: input.owner,
+            positionId: input.positionId, profileId: input.profileId, runId: input.runId ?? null, registeredAt: this.clock.now(), ...(note ? { note } : {}),
+        };
+        this.plans.set(input.mint, plan);
+        this.note('agent.paper.exit.plan', { ...plan, ...(input.restored === true ? { restored: true } : {}) });
+        return { ...plan };
+    }
+    /** The registered exit plans (read-only copies). */
+    exitPlans() { return [...this.plans.values()].map((p) => ({ ...p })); }
+    /**
+     * Sell a fraction of a planned position as one exit rule (P1): journaled `agent.paper.exit.<rule>` before the
+     * fill, the fill carries the note, and the plan is done once the position is empty. Runs in `close-only`.
+     */
+    async exit(input) {
+        const rule = exitRuleSlug(input.rule);
+        this.gate('exit', { mint: input.mint }, 'sell');
+        if (!rule)
+            this.refuse('exit', 'bad-request', 'an exit needs a rule name', { mint: input.mint });
+        const plan = this.plans.get(input.mint);
+        if (!plan)
+            this.refuse('exit', 'no-exit-plan', 'no exit plan is registered for this mint', { mint: input.mint, rule });
+        this.requireAction('exit', 'sell', { mint: input.mint });
+        this.requireMintAllowed('exit', input.mint, {});
+        const pos = this.wallet.position(input.mint);
+        if (!pos || pos.tokensRaw <= 0n)
+            this.refuse('exit', 'no-position', 'no open paper position in this mint to exit', { mint: input.mint, rule });
+        const fraction = input.fraction ?? 1;
+        if (!isFiniteNum(fraction) || !(fraction > 0 && fraction <= 1))
+            this.refuse('exit', 'bad-request', 'fraction must be in (0, 1]', { mint: input.mint, rule });
+        const t = { id: `pt_exit_${++this.ticketSeq}`, mint: input.mint, symbol: pos.symbol, decimals: pos.decimals, side: 'sell', usd: null, fraction, openedAt: this.clock.now() };
+        this.note(`agent.paper.exit.${rule}`, { planId: plan.planId, positionId: plan.positionId, mint: input.mint, fraction, ...(input.detail ? { detail: String(input.detail).slice(0, 200) } : {}) });
+        const order = await this.buildOrder('exit', t);
+        const base = sanitizeFillNote(input.note);
+        const note = { ...(typeof base === 'object' ? base : base ? { text: base } : {}), exit: rule, planId: plan.planId, positionId: plan.positionId };
+        const { rec, quoteAttempts } = await this.book('exit', order, { mint: input.mint, rule }, sanitizeFillNote(note));
+        this.planDoneIfEmpty(input.mint, rule);
+        return { fill: rec, position: this.positionView(this.wallet.position(input.mint)), quoteAttempts, plan: { ...plan }, rule: rule };
+    }
+    /**
+     * A read-only sell QUOTE for a fraction of a held position (what an exit would net, after the simulated fee),
+     * for sizing a cost-recovery slice (task-1506). It books nothing and journals only a refusal.
+     */
+    async previewSell(input) {
+        this.gate('preview', { mint: input.mint }, 'sell');
+        const pos = this.wallet.position(input.mint);
+        if (!pos || pos.tokensRaw <= 0n)
+            this.refuse('preview', 'no-position', 'no open paper position in this mint', { mint: input.mint });
+        const fraction = input.fraction;
+        if (!isFiniteNum(fraction) || !(fraction > 0 && fraction <= 1))
+            this.refuse('preview', 'bad-request', 'fraction must be in (0, 1]', { mint: input.mint });
+        const t = { id: `pt_preview_${++this.ticketSeq}`, mint: input.mint, symbol: pos.symbol, decimals: pos.decimals, side: 'sell', usd: null, fraction, openedAt: this.clock.now() };
+        const order = await this.buildOrder('preview', t);
+        const { quote } = await this.freshQuote('preview', order, { mint: input.mint });
+        const f = this.executor.previewFill(order, quote);
+        return { amountRaw: order.amountRaw, solOut: lamportsToSol(f.solDelta > 0n ? f.solDelta : 0n), priceImpactPct: f.priceImpactPct };
+    }
+    /** Once a planned position is empty its plan is done (journaled once). */
+    planDoneIfEmpty(mint, by) {
+        const plan = this.plans.get(mint);
+        if (!plan)
+            return;
+        const pos = this.wallet.position(mint);
+        if (pos && pos.tokensRaw > 0n)
+            return;
+        this.plans.delete(mint);
+        this.note('agent.paper.exit.done', { planId: plan.planId, positionId: plan.positionId, mint, by });
+    }
+}
 export { SOL_MINT };

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

@@ -54,8 +54,9 @@ export function readPaperAgentRendezvous(env = process.env) {
         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. */
+const VALID_STATES = ['running', 'paused', 'stopped', 'takeover', 'close-only'];
+/** Write the live control state (0600). The app calls this on pause / take-over / stop / resume, and autotrade's
+ *  soft stop writes `close-only` (task-1506 P2: exits keep running, buys are refused). */
 export function writeDeskControl(control, env = process.env) {
     const p = paperAgentControlPath(env);
     mkdirSync(dirname(p), { recursive: true, mode: 0o700 });

package/dist/packages/data/src/trade/bridge.js

@@ -7,9 +7,7 @@
 // Security posture (mirrors research/popup-host/server/server.mjs §5):
 //   * listens on 127.0.0.1 only; never 0.0.0.0 / ::. task-1368 (g): on a FIXED preferred port
 //     (`WALLET_BRIDGE_PORT`, random only when it is busy) — Phantom remembers trust PER ORIGIN, and a
-//     random port made every page a brand-new origin: the sign page then called signTransaction on an
-//     origin Phantom had never connected and got 4100 ("not authorized"). The sign page now connects
-//     first and checks the account; the stable origin lets that connect resolve silently next time.
+//     random port made every page a brand-new origin, so Phantom asked to connect every time.
 //   * a single-use, random 32-byte TOKEN in the URL; a second use is refused (replay-proof).
 //   * strict Host check on every request; strict Origin + JSON content-type + 16 KB body cap on POST.
 //   * remote address must be loopback; anything else gets an empty 404.
@@ -23,32 +21,13 @@
 import http from 'node:http';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { mkdtempSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { systemClock } from "../clock.js";
 import { base58 } from "../sources/solana-rpc.js";
 import { verifyEd25519 } from "./tx-decode.js";
 const TOKEN_TTL_MS = 120_000;
-/**
- * task-1328: the tx-sign page needs @solana/web3.js in the BROWSER (Phantom's signTransaction takes a
- * VersionedTransaction object). The vendored IIFE bundle (packages/data/vendor/solana-web3, MIT,
- * sha256-pinned by the tests) is inlined into the page under the CSP nonce — no CDN, no remote script.
- * Read lazily and cached; a missing file leaves the page in its "needs the shell" state (closed).
- */
-export const SOLANA_WEB3_VENDOR = new URL('../../vendor/solana-web3/index.iife.min.js', import.meta.url);
-let web3Bundle;
-export function solanaWeb3Bundle() {
-    if (web3Bundle !== undefined)
-        return web3Bundle;
-    try {
-        web3Bundle = readFileSync(SOLANA_WEB3_VENDOR, 'utf8');
-    }
-    catch {
-        web3Bundle = null;
-    }
-    return web3Bundle;
-}
 const MAX_BODY = 16 * 1024;
 const LOOPBACK = new Set(['127.0.0.1', '::ffff:127.0.0.1', '::1']);
 function spawnOpener(target) {
@@ -93,7 +72,7 @@ export const systemBrowserOpener = (url) => {
 };
 /**
  * The wallet bridge's preferred loopback port: `http://127.0.0.1:41291` is the ORIGIN Phantom stores
- * its trust for (link and sign share it). Unassigned by IANA; the X login callback is 41287.
+ * its trust for. Unassigned by IANA; the X login callback is 41287.
  */
 export const WALLET_BRIDGE_PORT = 41291;
 function b64url(buf) { return buf.toString('base64url'); }
@@ -223,7 +202,7 @@ function oneShot(args) {
                 res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
                 res.end(JSON.stringify({ ok: out.error === undefined, error: out.error ?? null }));
                 // Resolve (and close every connection) only once the page has its answer: `finish` now tears
-                // the socket down, and the page's "✓ signed" line reads this response.
+                // the socket down, and the page's "✓ linked" line reads this response.
                 if (out.error === undefined) {
                     const done = () => finish(() => resolve(out.value));
                     res.once('finish', done);
@@ -350,38 +329,6 @@ export class WalletBridge {
             },
         });
     }
-    /**
-     * Hand an unsigned transaction to the wallet for signing and resolve with the signed bytes. dexterm
-     * never holds a key; the browser approval IS the physical confirmation (SPEC §6.5). The unsigned tx
-     * is the plan the user already confirmed; a popup-host lane can swap the page for a chromeless window.
-     */
-    signTransaction(args) {
-        const started = this.clock.now();
-        return oneShot({
-            route: 'sign',
-            open: this.open,
-            timeoutMs: this.timeoutMs,
-            clock: this.clock,
-            preferredPort: this.port,
-            page: ({ port, nonce: cspNonce, portNote }) => signPage(port, cspNonce, args.unsignedTxBase64, args.expectPublicKey ?? '', args.label ?? 'swap', portNote),
-            onResult: (body) => {
-                // task-1368 (g): the page reports which account signed (base58). When the caller named the
-                // linked wallet, a different account is refused HERE too — the page's own check is UX, this is
-                // the gate (the signer also verifies the signature over the bytes; this is belt and braces).
-                const account = str(body.publicKey);
-                if (args.expectPublicKey && account !== '' && account !== args.expectPublicKey)
-                    return { error: `signed by a different wallet account (${sanitize(account, 8)}…), not the linked wallet` };
-                const signed = str(body.signedTx);
-                if (signed.length === 0)
-                    return { error: 'wallet returned no signed transaction' };
-                if (signed.length > 4096)
-                    return { error: 'signed transaction too large' };
-                if (!/^[A-Za-z0-9+/=]+$/.test(signed))
-                    return { error: 'signed transaction is not base64' };
-                return { value: { signedTxBase64: signed, provider: sanitize(body.provider ?? 'unknown', 24), roundTripMs: this.clock.now() - started } };
-            },
-        });
-    }
 }
 // --------------------------------------------------------------------------- inlined browser pages
 // These run in the user's browser (real Phantom). The fake-Phantom e2e POSTs the result directly, so
@@ -417,48 +364,3 @@ const j=await rp.json();if(j.ok){$('r').textContent='✓ linked. Return to dexte
 catch(e){$('r').textContent='✗ '+(e&&e.message||e);$('r').className='bad';$('s').textContent='';$('go').disabled=false;}}
 $('go').addEventListener('click',run);poll(0);})();</script></body></html>`.replace('"__T__"', `new URLSearchParams(location.search).get('t')`);
 }
-function signPage(port, nonce, unsignedTxB64, expectPk, label, portNote = '') {
-    const web3 = solanaWeb3Bundle();
-    return `<!doctype html><html lang="en"><head><meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1"><title>dexterm · sign</title>
-<style nonce="${nonce}">body{font:14px/1.5 -apple-system,system-ui,sans-serif;background:#07090d;color:#d7dbe0;margin:0;padding:2rem}
-.card{max-width:640px;margin:auto;background:#0d1016;border:1px solid #1d2430;border-radius:12px;padding:1.5rem}
-h1{font-size:1.1rem;color:#7fd1ff}button{font:inherit;background:#531;border:1px solid #a62;color:#fec;border-radius:8px;padding:.5rem 1rem;cursor:pointer}
-.ok{color:#5de28a}.bad{color:#ff6b6b}.warn{color:#e2b85d}.muted{color:#7a828e}code{word-break:break-all}</style></head><body><div class="card">
-<h1>✦ dexterm · approve ${esc(label)}</h1>
-<p>Your terminal already showed you this trade and you pressed confirm. Approve it in your wallet to sign. dexterm submits the signed transaction; it never holds your key.</p>
-${portNote ? `<p class="warn">${esc(portNote)}</p>\n` : ''}<p id="p" class="warn">looking for a wallet…</p>
-<p><button id="go" disabled>Approve in wallet</button> <span id="s"></span></p>
-<p id="r"></p>
-<p class="muted">linked wallet: <code>${esc(expectPk || 'any')}</code> · connected: <code id="a">–</code></p></div>
-${web3 ? `<script nonce="${nonce}">${web3}\n;window.dexSolana=solanaWeb3;</script>` : ''}
-<script nonce="${nonce}">(()=>{'use strict';const $=i=>document.getElementById(i),PORT=${port},EXPECT=${JSON.stringify(expectPk)};
-const TX=${JSON.stringify(unsignedTxB64)};const b64=u=>btoa(String.fromCharCode.apply(null,u));
-const short=k=>k&&k.length>12?k.slice(0,4)+'…'+k.slice(-4):String(k||'?');
-// task-1368 (g): Phantom's error codes in plain English. 4100 = this origin was never connected (or the
-// user revoked it): the fix is the Connect prompt, not a retry of the signature.
-function explain(e){const code=e&&(e.code!==undefined?e.code:(e.error&&e.error.code));const msg=(e&&e.message)||String(e);
-if(code===4100)return 'Phantom has not authorized this page (4100). Press Approve again and accept the Connect prompt; if none appears, open Phantom → Settings → Trusted apps, allow 127.0.0.1:'+PORT+', then confirm the trade again in dexterm. Nothing was signed.';
-if(code===4001)return 'you rejected the request in Phantom; nothing was signed. Confirm again in dexterm to retry.';
-if(code===-32603)return 'Phantom could not process the transaction (internal error): '+msg;
-return msg;}
-function bytes(b){const s=atob(b),a=new Uint8Array(s.length);for(let i=0;i<s.length;i++)a[i]=s.charCodeAt(i);return a;}
-let prov=null,name='none';function find(){if(window.phantom&&window.phantom.solana&&window.phantom.solana.isPhantom)return[window.phantom.solana,'phantom'];if(window.solana&&window.solana.isPhantom)return[window.solana,'phantom'];if(window.solana)return[window.solana,window.solana.isStubWallet?'stub':'solana'];return[null,'none'];}
-function poll(n){[prov,name]=find();if(prov){$('p').textContent='wallet: '+name;$('p').className='ok';$('go').disabled=false;if(name==='stub')run();return;}if(n>40){$('p').textContent='No Solana wallet found.';$('p').className='bad';return;}setTimeout(()=>poll(n+1),100);}
-async function run(){$('go').disabled=true;$('s').textContent='connecting to your wallet…';try{
-// Real Phantom needs @solana/web3.js on the page to rebuild the VersionedTransaction before signTransaction().
-// The dexterm wallet shell (popup-host lane) provides it as window.dexSolana; see scripts/ for the manual path.
-if(!window.dexSolana||!window.dexSolana.VersionedTransaction)throw new Error('tx signing needs the dexterm wallet shell (window.dexSolana). See scripts/phantom-devnet.md.');
-// task-1368 (g): CONNECT FIRST. signTransaction() on an origin Phantom has not connected is a 4100, so
-// the page used to fail on every fresh (random-port) origin. connect() resolves silently on a trusted
-// origin and prompts once on a new one; then the connected account must be the wallet dexterm linked.
-const res=await prov.connect();const pk=(res&&res.publicKey)||prov.publicKey;const account=pk?(typeof pk.toBase58==='function'?pk.toBase58():String(pk)):'';
-if(!account)throw new Error('the wallet connected without a public key; nothing was signed');$('a').textContent=account;
-if(EXPECT&&account!==EXPECT)throw new Error('Phantom is on account '+short(account)+' but dexterm linked '+short(EXPECT)+'. Switch accounts in Phantom and press Approve again, or re-link with "dexterm wallet link". Nothing was signed.');
-$('s').textContent='approve in your wallet…';
-const vt=window.dexSolana.VersionedTransaction.deserialize(bytes(TX));const signed=await prov.signTransaction(vt);
-const out=b64(signed.serialize());const rp=await fetch('http://127.0.0.1:'+PORT+'/sign/result',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({t:${JSON.stringify('__T__')},signedTx:out,provider:name,publicKey:account})});
-const j=await rp.json();if(j.ok){$('r').textContent='✓ signed. Return to dexterm.';$('r').className='ok';$('s').textContent='done';}else{$('r').textContent='✗ '+(j.error||'rejected');$('r').className='bad';$('go').disabled=false;}}
-catch(e){$('r').textContent='✗ '+explain(e);$('r').className='bad';$('s').textContent='';$('go').disabled=false;}}
-$('go').addEventListener('click',run);poll(0);})();</script></body></html>`.replace('"__T__"', `new URLSearchParams(location.search).get('t')`);
-}