dexterm-cli 0.1.5 → 0.1.6

package/dist/packages/data/src/larp/x-account.js

@@ -0,0 +1,316 @@
+// LARP detector — keyless X account lookup (task-1471). Read-only, no login, no cookies, no X API key.
+//
+// Why a fallback chain: measured 2026-10-19 (handoff evidence x-repro.md), FxTwitter answers `404 User not found`
+// for accounts that exist on roughly one call in six, a missing handle gets a 302 to the project's GitHub page on
+// some calls, and "suspended" is reported only some of the time. vxtwitter serves a cached copy (its own
+// `fetched_on`, up to about a day old). X's own oEmbed endpoint says exists / missing and the canonical handle, and
+// nothing else. The X syndication timeline (429 / empty) and the Nitter-class mirrors (offline, suspended, or a 200
+// "offline" page) gave nothing usable and are not in the chain.
+//
+// So no single answer is a verdict: `active` needs one source returning the profile; `suspended` needs a source
+// saying so; `not_found` needs TWO independent sources (vxtwitter AND oEmbed) saying missing; anything else is
+// `unavailable`. Every field that could not be read is listed in `unavailable` and is never guessed.
+//
+// Politeness: one handle per user action, at most five calls, a per-host spacing limiter, a TTL cache, and a
+// circuit breaker per source (the shared HealthRegistry: 3 failures or 2× 429 in a minute → degraded, 30 s..10 min
+// backoff). The bio is untrusted text: the caller firewalls it before it reaches a model.
+import { HealthRegistry } from "../health.js";
+import { systemClock } from "../clock.js";
+import { parseHttpUrl } from "./links.js";
+const RESERVED = new Set(['i', 'home', 'search', 'intent', 'hashtag', 'share', 'explore', 'settings', 'messages', 'notifications', 'login', 'signup', 'tos', 'privacy', 'compose']);
+const HANDLE = /^[A-Za-z0-9_]{1,15}$/;
+const X_HOSTS = new Set(['x.com', 'twitter.com', 'mobile.twitter.com', 'mobile.x.com', 'fxtwitter.com', 'vxtwitter.com', 'fixupx.com', 'nitter.net']);
+const SOURCE_ID = { fxtwitter: 'fxtwitter', vxtwitter: 'vxtwitter', 'x-oembed': 'x-oembed' };
+const HOST = { fxtwitter: 'api.fxtwitter.com', vxtwitter: 'api.vxtwitter.com', 'x-oembed': 'publish.x.com' };
+/** Parse an advertised X link into its kind, handle and status id. Pure. */
+export function parseXLink(raw) {
+    const u = parseHttpUrl(raw);
+    if (!u)
+        return { kind: 'other', handle: null, statusId: null };
+    const host = u.hostname.toLowerCase().replace(/^www\./, '');
+    if (!X_HOSTS.has(host))
+        return { kind: 'other', handle: null, statusId: null };
+    const parts = u.pathname.split('/').filter(Boolean);
+    if (parts[0]?.toLowerCase() === 'i' && parts[1]?.toLowerCase() === 'communities')
+        return { kind: 'community', handle: null, statusId: null };
+    const h = parts[0] ?? '';
+    if (!HANDLE.test(h) || RESERVED.has(h.toLowerCase()))
+        return { kind: 'other', handle: null, statusId: null };
+    if (parts[1]?.toLowerCase() === 'status' && /^\d{1,25}$/.test(parts[2] ?? ''))
+        return { kind: 'status', handle: h, statusId: parts[2] };
+    return { kind: parts.length === 1 ? 'profile' : 'other', handle: h, statusId: null };
+}
+const json = (body) => {
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+};
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const str = (v) => (typeof v === 'string' && v ? v : null);
+const iso = (v) => { const t = typeof v === 'string' ? Date.parse(v) : NaN; return Number.isFinite(t) ? new Date(t).toISOString() : null; };
+const days = (now, at) => (at ? Math.max(0, Math.floor((now - Date.parse(at)) / 86_400_000)) : null);
+const bareHost = (raw) => { const u = raw ? parseHttpUrl(raw) : null; return u ? u.hostname.toLowerCase().replace(/^www\./, '') : null; };
+function mentionsToken(bio, ctx) {
+    const sym = (ctx.symbol ?? '').trim();
+    const name = (ctx.name ?? '').trim();
+    if (!sym && !name && !ctx.mint)
+        return null;
+    const b = bio.toLowerCase();
+    if (ctx.mint && bio.includes(ctx.mint))
+        return true;
+    if (sym.length >= 2 && new RegExp(`(^|[^a-z0-9])\\$?${sym.toLowerCase().replace(/[^a-z0-9]/g, '')}([^a-z0-9]|$)`).test(b))
+        return true;
+    if (name.length >= 3 && b.includes(name.toLowerCase()))
+        return true;
+    return false;
+}
+/** The lookup service: chain + cache + spacing + circuit breakers. One instance per process. */
+export class XAccountLookup {
+    fetchImpl;
+    clock;
+    health;
+    minIntervalMs;
+    ttlMs;
+    ttlUnavailableMs;
+    maxEntries;
+    cache = new Map();
+    lastCall = new Map();
+    constructor(opts) {
+        this.fetchImpl = opts.fetch;
+        this.clock = opts.clock ?? systemClock;
+        this.health = opts.health ?? new HealthRegistry({ clock: this.clock });
+        this.minIntervalMs = opts.minIntervalMs ?? 1000;
+        this.ttlMs = opts.ttlMs ?? 30 * 60_000;
+        this.ttlUnavailableMs = opts.ttlUnavailableMs ?? 10 * 60_000;
+        this.maxEntries = opts.maxEntries ?? 500;
+    }
+    /** Per-host spacing: calls to one host are serialized at least minIntervalMs apart. */
+    async spaced(host, fn) {
+        const prev = this.lastCall.get(host) ?? Promise.resolve();
+        let release;
+        const mine = new Promise((r) => { release = r; });
+        this.lastCall.set(host, prev.then(() => mine));
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            if (this.minIntervalMs > 0)
+                void this.clock.sleep(this.minIntervalMs).then(release);
+            else
+                release();
+        }
+    }
+    async get(source, endpoint, url, trace) {
+        const sid = SOURCE_ID[source];
+        if (!this.health.isAvailable(sid)) {
+            trace.push({ source, endpoint, status: null, result: 'skipped: circuit open (source degraded)', ms: 0 });
+            return null;
+        }
+        const t0 = this.clock.now();
+        try {
+            const r = await this.spaced(HOST[source], () => this.fetchImpl(url));
+            const ms = this.clock.now() - t0;
+            // 404 / 3xx are answers (a vote), not source failures; 429 and 5xx other than vxtwitter's suspended body are.
+            const failed = r.status === 0 || r.status === 429 || (r.status >= 500 && !/suspended/i.test(r.body));
+            this.health.record(sid, failed ? { ok: false, status: r.status, latencyMs: ms, error: `http ${r.status}` } : { ok: true, status: r.status, latencyMs: ms });
+            return { status: r.status, body: r.body, ms };
+        }
+        catch (e) {
+            const ms = this.clock.now() - t0;
+            this.health.record(sid, { ok: false, latencyMs: ms, error: e.message });
+            trace.push({ source, endpoint, status: null, result: `error: ${e.message}`.slice(0, 120), ms });
+            return null;
+        }
+    }
+    /** Look up the account behind an advertised X link. Never throws. */
+    async lookup(xUrl, ctx = {}) {
+        const link = parseXLink(xUrl);
+        const now = this.clock.now();
+        const key = `${link.handle?.toLowerCase() ?? xUrl}|${link.statusId ?? ''}|${(ctx.symbol ?? '').toLowerCase()}|${(ctx.name ?? '').toLowerCase()}|${ctx.mint ?? ''}|${bareHost(ctx.website) ?? ''}`;
+        const hit = this.cache.get(key);
+        if (hit && now - hit.at < (hit.report.status === 'unavailable' ? this.ttlUnavailableMs : this.ttlMs))
+            return { ...hit.report, cached: true };
+        const report = await this.uncached(xUrl, link, ctx);
+        this.cache.delete(key);
+        this.cache.set(key, { at: now, report });
+        while (this.cache.size > this.maxEntries)
+            this.cache.delete(this.cache.keys().next().value);
+        return report;
+    }
+    async uncached(url, link, ctx) {
+        const now = this.clock.now();
+        const trace = [];
+        const base = {
+            url, kind: link.kind, handle: link.handle, status: 'unavailable', screenName: null, id: null, renamed: null,
+            createdAt: null, ageDays: null, followers: null, following: null, tweets: null, lastPostAt: null, daysSinceLastPost: null,
+            bio: null, website: null, bioMentionsToken: null, linksSite: null, countsAsOf: null, countsSource: null,
+            unavailable: [], sources: trace, cached: false, fetchedAt: new Date(now).toISOString(),
+        };
+        if (!link.handle) {
+            base.unavailable = ['account (the X link is not an account or a post)'];
+            return base;
+        }
+        let h = link.handle;
+        // A status link: who wrote the post now. A different author means a renamed account or a borrowed post.
+        if (link.statusId) {
+            const r = await this.get('fxtwitter', 'status', `https://api.fxtwitter.com/${h}/status/${link.statusId}`, trace);
+            const j = r ? json(r.body) : null;
+            const author = str(j?.tweet?.author?.screen_name);
+            if (r)
+                trace.push({ source: 'fxtwitter', endpoint: 'status', status: r.status, result: author ? `post by @${author}` : `no post (${str(j?.message) ?? r.status})`, ms: r.ms });
+            if (author && author.toLowerCase() !== h.toLowerCase()) {
+                base.renamed = { from: h, to: author, evidence: `the linked post ${link.statusId} is now shown under @${author}` };
+                h = author;
+            }
+        }
+        let profile = null;
+        let suspended = false;
+        let missingVotes = 0;
+        const missingBy = [];
+        // 1) FxTwitter profile: fresh counts. A 404 is one vote only (measured false 404s).
+        const fx = await this.get('fxtwitter', 'profile', `https://api.fxtwitter.com/${h}`, trace);
+        if (fx) {
+            const j = json(fx.body);
+            const u = j?.user;
+            if (fx.status === 200 && u) {
+                profile = { screenName: str(u.screen_name), id: str(u.id), createdAt: iso(u.joined), followers: num(u.followers), following: num(u.following), tweets: num(u.tweets), bio: typeof u.description === 'string' ? u.description : null, website: str(u.website?.url), asOf: new Date(now).toISOString() };
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: 200, result: 'profile', ms: fx.ms });
+            }
+            else if (str(j?.reason) === 'suspended') {
+                suspended = true;
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: fx.status, result: 'suspended', ms: fx.ms });
+            }
+            else {
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: fx.status, result: fx.status >= 300 && fx.status < 400 ? 'redirect (missing handle or error page)' : `no profile (${str(j?.message) ?? fx.status})`, ms: fx.ms });
+            }
+        }
+        // 2) vxtwitter: cached copy; says suspended / missing reliably in the probe.
+        if (!profile) {
+            const vx = await this.get('vxtwitter', 'profile', `https://api.vxtwitter.com/${h}`, trace);
+            if (vx) {
+                const j = json(vx.body);
+                if (vx.status === 200 && j && str(j.screen_name)) {
+                    const fetchedOn = num(j.fetched_on);
+                    profile = { screenName: str(j.screen_name), id: j.id === undefined || j.id === null ? null : String(j.id), createdAt: iso(j.created_at), followers: num(j.followers_count), following: num(j.following_count), tweets: num(j.tweet_count), bio: typeof j.description === 'string' ? j.description : null, website: null, asOf: fetchedOn ? new Date(fetchedOn * 1000).toISOString() : null };
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: 200, result: 'profile (cached copy)', ms: vx.ms });
+                }
+                else if (/suspended/i.test(str(j?.error) ?? '')) {
+                    suspended = true;
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: vx.status, result: 'suspended', ms: vx.ms });
+                }
+                else if (vx.status === 404) {
+                    missingVotes++;
+                    missingBy.push('vxtwitter');
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: 404, result: 'not found', ms: vx.ms });
+                }
+                else
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: vx.status, result: 'no answer', ms: vx.ms });
+            }
+        }
+        // 3) X oEmbed: exists vs missing (200 for a suspended account too).
+        let oembedExists = null;
+        if (!profile && !suspended) {
+            const oe = await this.get('x-oembed', 'oembed', `https://publish.x.com/oembed?url=${encodeURIComponent(`https://x.com/${h}`)}`, trace);
+            if (oe) {
+                const j = json(oe.body);
+                if (oe.status === 200 && j) {
+                    oembedExists = true;
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: 200, result: 'exists', ms: oe.ms });
+                }
+                else if (oe.status === 404) {
+                    oembedExists = false;
+                    missingVotes++;
+                    missingBy.push('x-oembed');
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: 404, result: 'not found', ms: oe.ms });
+                }
+                else
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: oe.status, result: 'no answer', ms: oe.ms });
+            }
+        }
+        // 4) Last post date (FxTwitter statuses), only for an account that exists.
+        let lastPostAt = null;
+        let postsRead = false;
+        if (profile) {
+            const st = await this.get('fxtwitter', 'statuses', `https://api.fxtwitter.com/2/profile/${h}/statuses`, trace);
+            const j = st ? json(st.body) : null;
+            const results = Array.isArray(j?.results) ? j.results : null;
+            if (st?.status === 200 && results) {
+                postsRead = true;
+                const times = results.map((r) => iso(r.created_at)).filter((t) => !!t).sort();
+                lastPostAt = times.at(-1) ?? null;
+                trace.push({ source: 'fxtwitter', endpoint: 'statuses', status: 200, result: `${results.length} recent posts`, ms: st.ms });
+            }
+            else if (st)
+                trace.push({ source: 'fxtwitter', endpoint: 'statuses', status: st.status, result: 'posts unavailable', ms: st.ms });
+        }
+        const out = { ...base };
+        if (profile) {
+            out.status = 'active';
+            Object.assign(out, {
+                screenName: profile.screenName, id: profile.id, createdAt: profile.createdAt, ageDays: days(now, profile.createdAt),
+                followers: profile.followers, following: profile.following, tweets: profile.tweets,
+                bio: profile.bio !== null ? profile.bio.slice(0, 280) : null, website: profile.website,
+                countsAsOf: profile.asOf, countsSource: trace.find((t) => t.endpoint === 'profile' && t.status === 200)?.source ?? null,
+                lastPostAt, daysSinceLastPost: days(now, lastPostAt),
+            });
+            // A posts list that came back empty for an account with zero tweets is "no posts", not missing.
+            if (postsRead && !lastPostAt && profile.tweets === 0)
+                out.daysSinceLastPost = null;
+            out.bioMentionsToken = profile.bio !== null ? mentionsToken(profile.bio, ctx) : null;
+            const site = bareHost(ctx.website);
+            if (site) {
+                const bioHit = (profile.bio ?? '').toLowerCase().includes(site);
+                const webHit = bareHost(profile.website) === site;
+                out.linksSite = bioHit || webHit ? true : (profile.website !== null || profile.bio !== null) ? false : null;
+            }
+        }
+        else if (suspended)
+            out.status = 'suspended';
+        else if (missingVotes >= 2)
+            out.status = 'not_found';
+        else if (oembedExists)
+            out.status = 'unavailable'; // exists per X, but no source returned the profile
+        const miss = [];
+        if (out.status !== 'active') {
+            if (out.status === 'unavailable')
+                miss.push(`account status (${missingBy.length ? `only ${missingBy.join(' + ')} said missing; ` : ''}no source returned the profile)`);
+        }
+        else {
+            if (out.createdAt === null)
+                miss.push('account created date');
+            if (out.followers === null)
+                miss.push('follower count');
+            if (out.following === null)
+                miss.push('following count');
+            if (out.tweets === null)
+                miss.push('post count');
+            if (!postsRead)
+                miss.push('last post date');
+            if (out.bio === null)
+                miss.push('bio');
+            if (ctx.website && out.linksSite === null)
+                miss.push('site cross-link');
+            if (out.bioMentionsToken === null && (ctx.symbol || ctx.name))
+                miss.push('bio mentions the token');
+        }
+        out.unavailable = miss;
+        return out;
+    }
+}
+/** Advertised handles per source, and whether they and the site's own X links agree. Pure. */
+export function xHandleAgreement(advertised, siteLinks) {
+    const handles = advertised.map((l) => ({ h: parseXLink(l.url), source: l.source })).filter((x) => x.h.handle).map((x) => ({ handle: x.h.handle, source: x.source }));
+    const distinct = [...new Set(handles.map((x) => x.handle.toLowerCase()))];
+    const siteHandles = siteLinks === null ? null : [...new Set(siteLinks.map((u) => parseXLink(u)).filter((x) => x.kind === 'profile' && x.handle).map((x) => x.handle.toLowerCase()))];
+    const siteLinksAdvertised = siteHandles === null || !distinct.length ? null : siteHandles.length === 0 ? false : siteHandles.some((s) => distinct.includes(s));
+    const agree = distinct.length === 0 ? null : distinct.length === 1 && (siteHandles === null || siteHandles.length === 0 || siteHandles.includes(distinct[0]));
+    const siteAgrees = !distinct.length || !siteHandles?.length ? null : siteHandles.some((s) => distinct.includes(s));
+    const note = distinct.length > 1 ? `sources advertise different X accounts: ${distinct.map((d) => `@${d}`).join(', ')}`
+        : agree === false && siteHandles?.length ? `the website links @${siteHandles.join(', @')} but the token lists @${distinct[0]}` : null;
+    return { handles, agree, siteAgrees, siteHandles, siteLinksAdvertised, note };
+}

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

@@ -34,6 +34,17 @@ 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;
+}
 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 /
@@ -52,6 +63,8 @@ export class PaperAgentDesk {
     kill;
     clock;
     agent;
+    quoteRetry;
+    onQuoteRetry;
     tickets = new Map();
     ticketSeq = 0;
     constructor(deps) {
@@ -71,6 +84,9 @@ 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;
     }
     /** The agent's effective per-trade cap: the mandate cap times the weakest-tier multiplier. */
     perTradeCapUsd() {
@@ -221,9 +237,9 @@ export class PaperAgentDesk {
         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 { rec, quoteAttempts } = await this.book('confirm', order, { ticketId });
         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 };
     }
     /** Close a fraction of a held PAPER position in one call (open sell → size fraction → confirm). */
     async close(input) {
@@ -239,8 +255,8 @@ 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 { 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) {
@@ -265,15 +281,64 @@ 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 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) {
-        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);
-        }
+        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) {
@@ -293,7 +358,7 @@ export class PaperAgentDesk {
             solDelta: rec.solDelta.toString(), tokenDelta: rec.tokenDelta.toString(),
             priceSol: rec.priceSol, priceUsd: rec.priceUsd, realizedLamports: rec.realizedLamports.toString(), fillId: rec.id,
         });
-        return rec;
+        return { rec: rec, quoteAttempts: attempts };
     }
     // ───────────────────────────── the two reads ─────────────────────────────
     positionView(pos) {

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))

package/dist/packages/data/src/trade/plans/mandate.js

@@ -13,6 +13,15 @@ export const HARD = Object.freeze({
     tipBudgetLamports: 500_000_000, maxTipLamportsPerTx: 10_000_000, maxPriorityFeeLamportsPerTx: 10_000_000,
     ttlMs: 24 * 3600_000, maxSendsPerSec: 20,
 });
+/**
+ * task-1469: ceilings for a PAPER-ONLY mandate (`dexterm mandate draft --paper`). Only the agent paper desk reads
+ * one: the plan engine refuses to arm a plan into it, fire under it or copy-trade through it, so these numbers never
+ * reach a signer, and HARD (above) stays the ceiling of every mandate a real fill can use. Fills are still priced
+ * on a live quote, so a bigger paper size pays its real price impact.
+ */
+export const PAPER_HARD = Object.freeze({
+    ...HARD, totalUsd: 10_000, perTradeUsd: 2_000, perCoinUsd: 2_000, dailyLossUsd: 10_000, maxPriceImpactPct: 10,
+});
 /** Confirmation tiers and the multiplier they apply to a mandate's per-trade cap for plans confirmed that way. */
 export const TIERS = Object.freeze({
     'keypress': { rank: 0, perTradeMultiplier: 1.0, canArmMandate: true, canArmBatch: true },
@@ -37,6 +46,8 @@ function clamp(v, dflt, hardMax) {
 export function draftMandate(input, ctx) {
     const x = input ?? {};
     const now = ctx.clock.now();
+    const paper = x.paperOnly === true;
+    const H = paper ? PAPER_HARD : HARD;
     const actions = Array.isArray(x.actions) ? x.actions.filter((a) => a === 'buy' || a === 'sell') : ['buy', 'sell'];
     if (actions.length === 0)
         throw new MandateError('bad-request', 'at least one of buy/sell');
@@ -45,23 +56,23 @@ export function draftMandate(input, ctx) {
         id: ctx.id ?? `mandate_${now.toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
         wallet: 'fast', // the capped fast wallet; the main wallet is never named here
         budget: {
-            totalUsd: clamp(x.totalUsd, 100, HARD.totalUsd),
-            perTradeUsd: clamp(x.perTradeUsd, 20, HARD.perTradeUsd),
-            perCoinUsd: clamp(x.perCoinUsd, 40, HARD.perCoinUsd),
-            dailyLossUsd: clamp(x.dailyLossUsd, 50, HARD.dailyLossUsd),
+            totalUsd: clamp(x.totalUsd, 100, H.totalUsd),
+            perTradeUsd: clamp(x.perTradeUsd, 20, H.perTradeUsd),
+            perCoinUsd: clamp(x.perCoinUsd, 40, H.perCoinUsd),
+            dailyLossUsd: clamp(x.dailyLossUsd, 50, H.dailyLossUsd),
         },
         limits: {
-            maxArmedPlans: clamp(x.maxArmedPlans, 20, HARD.maxArmedPlans),
-            maxInFlight: clamp(x.maxInFlight, 5, HARD.maxInFlight),
-            maxOpenPositions: clamp(x.maxOpenPositions, 20, HARD.maxOpenPositions),
-            maxSlippageBps: clamp(x.maxSlippageBps, 500, HARD.maxSlippageBps),
-            maxPriceImpactPct: clamp(x.maxPriceImpactPct, 3, HARD.maxPriceImpactPct),
-            maxSendsPerSec: clamp(x.maxSendsPerSec, 5, HARD.maxSendsPerSec),
+            maxArmedPlans: clamp(x.maxArmedPlans, 20, H.maxArmedPlans),
+            maxInFlight: clamp(x.maxInFlight, 5, H.maxInFlight),
+            maxOpenPositions: clamp(x.maxOpenPositions, 20, H.maxOpenPositions),
+            maxSlippageBps: clamp(x.maxSlippageBps, 500, H.maxSlippageBps),
+            maxPriceImpactPct: clamp(x.maxPriceImpactPct, 3, H.maxPriceImpactPct),
+            maxSendsPerSec: clamp(x.maxSendsPerSec, 5, H.maxSendsPerSec),
         },
         fees: {
-            tipBudgetLamports: clamp(x.tipBudgetLamports, 50_000_000, HARD.tipBudgetLamports),
-            maxTipLamportsPerTx: clamp(x.maxTipLamportsPerTx, 1_000_000, HARD.maxTipLamportsPerTx),
-            maxPriorityFeeLamportsPerTx: clamp(x.maxPriorityFeeLamportsPerTx, 2_000_000, HARD.maxPriorityFeeLamportsPerTx),
+            tipBudgetLamports: clamp(x.tipBudgetLamports, 50_000_000, H.tipBudgetLamports),
+            maxTipLamportsPerTx: clamp(x.maxTipLamportsPerTx, 1_000_000, H.maxTipLamportsPerTx),
+            maxPriorityFeeLamportsPerTx: clamp(x.maxPriorityFeeLamportsPerTx, 2_000_000, H.maxPriorityFeeLamportsPerTx),
         },
         allowed: {
             actions,
@@ -70,8 +81,9 @@ export function draftMandate(input, ctx) {
         },
         maxTier: (typeof x.maxTier === 'string' && x.maxTier in TIERS) ? x.maxTier : 'keypress',
         createdAt: now,
-        expiresAt: now + clamp(x.ttlMs, 4 * 3600_000, HARD.ttlMs),
+        expiresAt: now + clamp(x.ttlMs, 4 * 3600_000, H.ttlMs),
         status: 'draft', armedAt: null, armedBy: null, revokedAt: null, revokedReason: null,
+        ...(paper ? { paperOnly: true } : {}),
     };
     // perTrade can never exceed total; perCoin never exceeds total.
     m.budget.perTradeUsd = Math.min(m.budget.perTradeUsd, m.budget.totalUsd);
@@ -117,7 +129,8 @@ export function revokeMandate(m, reason, ctx) {
 }
 /** Hash of the caps a gesture arms — the proof binds to these numbers, not to the mandate id alone. */
 export function capsHash(m) {
-    return createHash('sha256').update(JSON.stringify({ b: m.budget, l: m.limits, f: m.fees, a: m.allowed, t: m.maxTier, e: m.expiresAt, w: m.wallet })).digest('hex').slice(0, 16);
+    // task-1469: the paper-only flag is part of what a gesture arms; a normal mandate hashes exactly as before.
+    return createHash('sha256').update(JSON.stringify({ b: m.budget, l: m.limits, f: m.fees, a: m.allowed, t: m.maxTier, e: m.expiresAt, w: m.wallet, ...(m.paperOnly === true ? { p: 1 } : {}) })).digest('hex').slice(0, 16);
 }
 /** Alive = armed and not expired. Expiry is checked on every call, never cached. */
 export function mandateAlive(m, now) {

package/dist/packages/data/src/trade/plans/service.js

@@ -149,7 +149,7 @@ export class PlanService {
             return {
                 id: x.m.id, status: x.m.status, wallet: x.m.wallet, totalUsd: x.m.budget.totalUsd, perTradeUsd: x.m.budget.perTradeUsd,
                 perCoinUsd: x.m.budget.perCoinUsd, maxTier: x.m.maxTier, reservedUsd: L.reservedUsd, spentUsd: L.spentUsd,
-                realizedUsd: L.realizedUsd, lossUsd: L.lossUsd, expiresAt: x.m.expiresAt,
+                realizedUsd: L.realizedUsd, lossUsd: L.lossUsd, expiresAt: x.m.expiresAt, paperOnly: x.m.paperOnly === true,
             };
         });
     }

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

@@ -29,4 +29,4 @@ sources:
 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.
+The token screen's ON-CHAIN panel shows the creator's recorded track record (0.1.5): `Dev rugs` (rugs out of labelled prior launches, e.g. `2/3 · n=3 · rec 7d`), `Dev launches` (`n=3 · rec 2h · dev:jup`: which feed named the creator), `Dev sold bag` (median minutes to the dev's exit, `med 20m · n=3 · rec 1d`), `Dev linked` (funder or cluster from the wallet-intel scan, with the scan's age) and `Linked dev rugs` (rugs by other wallets in that cluster). Every value names its source (`rec` = the recorder, `scan` = the wallet-intel scan), its sample (n=) and the age of its newest datum. 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/larp-check.md

@@ -15,12 +15,16 @@ tags:
   - domain
   - github
   - vet
+  - score
+  - x
+  - twitter
 tools:
   - larp_check
   - get_links
   - fetch_page
   - check_domain
   - check_github
+  - check_x
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -33,4 +37,4 @@ sources:
 date: 2026-10-16
 ---
 
-The LARP check vets whether a real product exists (website, domain age, GitHub) read-only — it is not a price call. Ask the analyst "is <coin> a larp?" (skill `larp-check`), or an agent can call the `larp_check` MCP tool. A grade is a risk flag, never a certificate; it never recommends buy/sell.
+The LARP check vets whether a real product exists (website, domain age, GitHub, the X account) read-only — it is not a price call. Ask the analyst "is <coin> a larp?" (skill `larp-check`), or an agent can call the `larp_check` MCP tool. It returns a 0-100 LARP score: the sum of named flags with their points (low under 25, medium 25-49, high 50+), plus a list of what could not be read, which widens the range instead of lowering the score. A score is a summary of flags, never a certificate; it never recommends buy/sell.

package/dist/packages/mcp/assets/kb/app-help/scan-mode.md

@@ -32,6 +32,6 @@ sources:
 date: 2026-10-16
 ---
 
-Scan mode is an observe-only AI watcher (off by default, zero extra requests). Toggle it with `Z` (or `/scan on|off` on the screener line, or `--scan` at launch); `R` resumes a paused scan. It can only surface findings, never take a UI action or trade (structurally observe-only). The analyst can turn it on or off for you.
+Scan mode is an observe-only AI watcher (off by default, zero extra requests). Toggle it with `Z` (or `/scan on|off` on the screener line, or `--scan` at launch); `R` resumes a paused scan. It can only surface findings, never take a UI action or trade (structurally observe-only). While it is on, the token screen's analyst panel shows its brain view: the scan log (locks, refreshes, releases, blocked actions) with the read streaming under it, the vetting checklist and the data strip. While it runs and you hold a paper or live position, a PnL chip shows it on the band under the header of every screen and on the chart popup; display only. The analyst can turn it on or off for you.
 
 Keys: `Z`, `R`.

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

@@ -63,6 +63,7 @@ keys:
   - T
   - L
   - C
+  - A
   - I
   - F
   - Z
@@ -132,6 +133,7 @@ actions:
   - open.tg
   - open.links
   - popup.chart
+  - display.chartAxis
   - popup.token
   - tape.toggle
   - scan.toggle
@@ -218,6 +220,7 @@ Keys on this screen:
   `T` — open TG
   `L` — links
   `C` — chart popup
+  `A` — chart axis mcap ⇄ price
   `I` — token popup
   `F` — flow ⇄ tape
   `Z` — AI scan