dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/autotrade/src/signal.js

@@ -0,0 +1,196 @@
+// dexterm autotrade — the LIVE TRADE FIRE signal, `dexterm-trade-fire/1` (task-1645, 0.2.0 card A).
+//
+// A strategy in mode "real" trades exactly like paper (same clamp, exits, monitor and ledger: the paper fill model is
+// the monitor's own view), and every buy or sell it fills also becomes one of these signals for the user's OWN
+// executor (a Telegram trading bot of their choice, or any script). dexterm holds no key, signs no transaction and
+// builds none: a signal is a request the executor may act on, ignore, or reject.
+//
+//   type "trade"    side buy|sell, mint, sanitized symbol, size in SOL / USD / % of book (a sell also as the fraction
+//                   of the position), price + mcap + liquidity context, exit reason for a sell, strategy id/version/
+//                   hash, run id, account id, nonce, idempotency key, issued/expires, `paper: false`
+//   type "halted"   the run stopped (end, halt, kill, a lost runner): every outstanding signal's nonce, a reason, and
+//                   `open`: the mints dexterm still counts as held for the account (the next real run of the
+//                   strategy takes them over and keeps their exits; they still count against the open-position cap)
+//   type "test"     `dexterm autotrade signal test`: proves the channel; an executor must never trade on it
+//
+// Rules an executor follows (and SignalReceiver below implements, for scripts and the tests' fake executors):
+//   1. verify the HMAC header when a secret is set (`x-dexterm-signature: t=<unix s>,v1=<hex>` over "<t>.<body>")
+//   2. ignore anything past `expiresAt` (the TTL): a late signal is never acted on
+//   3. dedupe by nonce (and the idempotency key `id`): delivery is at-least-once, so a repeat is normal
+//   4. act only on the account id it was set up for
+//
+// Firewall: nothing token-authored rides along except the symbol, reduced to [A-Za-z0-9._$-] (16 chars). No name,
+// no description, no links, no agent text, no paths, no keys. Every other field is an engine number or an id that
+// dexterm validated itself.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+export const TRADE_FIRE_SCHEMA = 'dexterm-trade-fire/1';
+export const SIGNAL_TTL_DEFAULT_SEC = 60;
+export const SIGNAL_TTL_MIN_SEC = 10;
+export const SIGNAL_TTL_MAX_SEC = 600;
+/** How far a signature's timestamp may sit from the receiver's clock. */
+export const SIGNATURE_TOLERANCE_SEC = 300;
+const SOL_MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const ACCOUNT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const RUN_RE = /^[A-Za-z0-9._:-]{1,96}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+/** The only token text a signal carries: NFKC, then [A-Za-z0-9._$-] only, 16 chars, '?' when nothing is left. */
+export function sanitizeSymbol(s) {
+    const t = String(s ?? '').normalize('NFKC').replace(/[^A-Za-z0-9._$-]/g, '').slice(0, 16);
+    return t || '?';
+}
+/** An engine reason ("hard-stop", "time_review:no-answer") reduced to [a-z0-9:_-], 40 chars. */
+export function sanitizeReason(s) {
+    return String(s ?? '').toLowerCase().replace(/[^a-z0-9:_-]/g, '-').replace(/-+/g, '-').slice(0, 40) || 'unknown';
+}
+export const signalIdOf = (accountId, runId, nonce) => createHash('sha256').update(`${TRADE_FIRE_SCHEMA}|${accountId}|${runId}|${nonce}`).digest('hex').slice(0, 32);
+export const clampTtl = (sec) => Math.min(SIGNAL_TTL_MAX_SEC, Math.max(SIGNAL_TTL_MIN_SEC, Math.round(Number.isFinite(sec) ? sec : SIGNAL_TTL_DEFAULT_SEC)));
+const r6 = (v) => Math.round(v * 1e6) / 1e6;
+const r2 = (v) => Math.round(v * 100) / 100;
+const fin = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+function base(type, h) {
+    const ttlSec = clampTtl(h.ttlSec);
+    return {
+        schema: TRADE_FIRE_SCHEMA, type, id: signalIdOf(h.accountId, h.runId, h.nonce), nonce: h.nonce, issuedAt: h.now, expiresAt: h.now + ttlSec * 1000, ttlSec,
+        runId: h.runId, accountId: h.accountId, strategy: { id: h.strategy.id, version: h.strategy.version, hash: h.strategy.hash.slice(0, 64) }, paper: false,
+    };
+}
+/** A trade signal; throws on anything that is not a plain engine value (fail closed: no signal rather than a bad one). */
+export function buildTradeSignal(t, h) {
+    if (!SOL_MINT_RE.test(t.mint))
+        throw new Error('signal: mint is not a base58 address');
+    if (!(t.solUsd > 0))
+        throw new Error('signal: no SOL/USD price');
+    // A buy states a positive size; a sell's size is the modelled proceeds and can be ~0 (a rug exit must still go out).
+    if (t.side === 'buy' ? !(t.sizeUsd > 0) : !(t.sizeUsd >= 0))
+        throw new Error('signal: size must be positive');
+    const s = {
+        ...base('trade', h), type: 'trade', side: t.side, mint: t.mint, symbol: sanitizeSymbol(t.symbol),
+        sizeSol: r6(t.sizeUsd / t.solUsd), sizeUsd: r2(t.sizeUsd), pctOfBook: t.bookUsd > 0 ? Math.round((t.sizeUsd / t.bookUsd) * 1000) / 10 : 0,
+        sellFraction: t.side === 'sell' ? Math.min(1, Math.max(0, r6(t.sellFraction ?? 1))) : null,
+        price: { usd: fin(t.priceUsd), mcap: fin(t.mcap), liqUsd: fin(t.liqUsd), solUsd: r2(t.solUsd) },
+        exitReason: t.side === 'sell' ? sanitizeReason(t.exitReason) : null,
+        slippageBps: Math.round(t.slippageBps), maxImpactPct: t.maxImpactPct, positionId: t.positionId && /^[A-Za-z0-9._-]{1,48}$/.test(t.positionId) ? t.positionId : null,
+        ...(t.model ? { model: { priceUsd: fin(t.model.priceUsd), tokens: fin(t.model.tokens) } } : {}),
+    };
+    const v = validateSignal(s);
+    if (!v.ok)
+        throw new Error(`signal: ${v.error}`);
+    return s;
+}
+export function buildHaltedSignal(reason, outstanding, h, open = []) {
+    return { ...base('halted', h), type: 'halted', reason: sanitizeReason(reason), outstanding: [...new Set(outstanding)].filter((n) => Number.isInteger(n) && n > 0).sort((a, b) => a - b).slice(0, 500), open: [...new Set(open)].filter((m) => SOL_MINT_RE.test(m)).sort().slice(0, 100) };
+}
+export function buildTestSignal(h) {
+    return { ...base('test', h), type: 'test', test: true, note: 'channel test: never trade on this' };
+}
+/** One line of JSON, fixed key order (the webhook body, the hook's stdin, the stream line: byte-identical). */
+export const signalLine = (s) => JSON.stringify(s);
+/** Strict shape check: used on replay of the outbox and by receivers. */
+export function validateSignal(x) {
+    const s = x;
+    if (!s || typeof s !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (s.schema !== TRADE_FIRE_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (s.type !== 'trade' && s.type !== 'halted' && s.type !== 'test')
+        return { ok: false, error: 'type' };
+    if (!Number.isSafeInteger(s.nonce) || s.nonce < 1)
+        return { ok: false, error: 'nonce' };
+    if (typeof s.id !== 'string' || !HEX32.test(s.id))
+        return { ok: false, error: 'id' };
+    if (typeof s.accountId !== 'string' || !ACCOUNT_ID_RE.test(s.accountId))
+        return { ok: false, error: 'accountId' };
+    if (typeof s.runId !== 'string' || !RUN_RE.test(s.runId))
+        return { ok: false, error: 'runId' };
+    if (s.id !== signalIdOf(s.accountId, s.runId, s.nonce))
+        return { ok: false, error: 'id does not match account/run/nonce' };
+    if (s.paper !== false)
+        return { ok: false, error: 'paper must be false' };
+    if (!fin(s.issuedAt) || !fin(s.expiresAt) || s.expiresAt <= s.issuedAt)
+        return { ok: false, error: 'times' };
+    const st = s.strategy;
+    if (!st || typeof st.id !== 'string' || !ID_RE.test(st.id) || typeof st.version !== 'string' || typeof st.hash !== 'string')
+        return { ok: false, error: 'strategy' };
+    if (s.type === 'trade') {
+        if (s.side !== 'buy' && s.side !== 'sell')
+            return { ok: false, error: 'side' };
+        if (typeof s.mint !== 'string' || !SOL_MINT_RE.test(s.mint))
+            return { ok: false, error: 'mint' };
+        if (typeof s.symbol !== 'string' || s.symbol !== sanitizeSymbol(s.symbol))
+            return { ok: false, error: 'symbol' };
+        if (s.side === 'buy' ? !(fin(s.sizeSol) > 0) || !(fin(s.sizeUsd) > 0) : !(fin(s.sizeSol) >= 0) || !(fin(s.sizeUsd) >= 0))
+            return { ok: false, error: 'size' };
+        if (s.side === 'sell' && !(fin(s.sellFraction) > 0 && s.sellFraction <= 1))
+            return { ok: false, error: 'sellFraction' };
+    }
+    if (s.type === 'test' && s.test !== undefined && s.test !== true)
+        return { ok: false, error: 'test' };
+    if (s.type === 'test' && 'mint' in s)
+        return { ok: false, error: 'a test signal names no mint' };
+    if (s.type === 'trade' && s.model !== undefined && (typeof s.model !== 'object' || s.model === null))
+        return { ok: false, error: 'model' };
+    if (s.type === 'halted' && s.open !== undefined && (!Array.isArray(s.open) || s.open.length > 100 || !s.open.every((m) => typeof m === 'string' && SOL_MINT_RE.test(m))))
+        return { ok: false, error: 'open' };
+    return { ok: true, signal: s };
+}
+// ───────────────────────────── HMAC ─────────────────────────────
+/** `t=<unix s>,v1=<hex sha256 hmac of "<t>.<body>">`. */
+export function signBody(secret, body, nowMs) {
+    const t = Math.floor(nowMs / 1000);
+    return `t=${t},v1=${createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')}`;
+}
+export function verifyBody(secret, header, body, nowMs, toleranceSec = SIGNATURE_TOLERANCE_SEC) {
+    const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/.exec(String(header ?? ''));
+    if (!m)
+        return { ok: false, why: 'signature-missing' };
+    const t = Number(m[1]);
+    if (Math.abs(nowMs / 1000 - t) > toleranceSec)
+        return { ok: false, why: 'signature-stale' };
+    const want = createHmac('sha256', secret).update(`${t}.${body}`).digest();
+    const got = Buffer.from(m[2], 'hex');
+    return got.length === want.length && timingSafeEqual(got, want) ? { ok: true } : { ok: false, why: 'signature-bad' };
+}
+/**
+ * What a well-behaved executor does with an incoming signal: signature (when a secret is set), shape, account, TTL,
+ * replay (nonce and id). A duplicate is reported as such so a transport can ack it (at-least-once delivery).
+ * Exported for users' scripts and for the fake executors of the tests; dexterm itself never executes anything.
+ */
+export class SignalReceiver {
+    seen = new Set();
+    maxNonce = 0;
+    o;
+    constructor(o) { this.o = o; }
+    receive(body, signature) {
+        const now = (this.o.now ?? Date.now)();
+        if (this.o.secret) {
+            const v = verifyBody(this.o.secret, signature, body, now);
+            if (!v.ok)
+                return { ok: false, why: v.why };
+        }
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            return { ok: false, why: 'not-json' };
+        }
+        const v = validateSignal(raw);
+        if (!v.ok)
+            return { ok: false, why: `invalid:${v.error}` };
+        const s = v.signal;
+        if (s.accountId !== this.o.accountId)
+            return { ok: false, why: 'wrong-account', signal: s };
+        if (this.seen.has(s.id) || this.seen.has(`n${s.nonce}`))
+            return { ok: false, why: 'duplicate', signal: s };
+        if (now > s.expiresAt)
+            return { ok: false, why: 'expired', signal: s };
+        // A nonce at or below one already acted on (that is not a duplicate of it) is a replay of an old signal.
+        if (s.nonce <= this.maxNonce && s.type !== 'halted')
+            return { ok: false, why: 'nonce-replay', signal: s };
+        this.seen.add(s.id);
+        this.seen.add(`n${s.nonce}`);
+        this.maxNonce = Math.max(this.maxNonce, s.nonce);
+        return { ok: true, signal: s };
+    }
+}

package/dist/packages/autotrade/src/strategy-stats.js

@@ -0,0 +1,344 @@
+// dexterm autotrade — STRATEGY STATS for the performance dashboard (task-1749). Read-only over the run ledgers
+// ($DEXTERM_HOME/autotrade/runs/*.jsonl): no network, no model, no key, never writes.
+//
+// The definitions are the challenge control's (launch/send-out/challenge-100x/control/report.mjs + mine.mjs, task-1697 /
+// task-1733), so the dashboard and the control report count the same things the same way:
+//   entries   each position once across restarts (its first fill or adoption), keyed per run FILE + engine id
+//   closed    `trade_closed` (deduped) + WRITE-OFFS: a position the engine marked `stuck` (no pool to sell into) with no
+//             sell for >= 30 min, or dropped stuck at a clean run end, closes at its REALIZABLE value: the sells it made
+//             are kept, the unsold remainder counts 0. Derived here; the engine's ledgers are never edited.
+//   abandoned still open when a run ended cleanly and not stuck: the engine does not carry it, its outcome never enters
+//             the closed sample
+//   rugs      a closed position at <= -80% on cost (a write-off is a rug only at <= -80%)
+//   mean      mean % on cost with a 95% seeded percentile bootstrap (4000 resamples, seed 7); a difference of two
+//             strategies is a bootstrap of independent groups (seed 11); rates use the Wilson 95% interval
+//   sample    under 20 closed is EXPLORATORY; the ETA to 20 closed = (20 - closed) / entries per day since the first event
+// One difference from report.mjs (a fix, test/strategy-stats-1749.test.ts): the engine's crash recovery names an adopted
+// position `<runId>/pN` while that run's own fills said `pN`; report.mjs keys `pN` and so counted an adopted position
+// two or three times. Here `<runId>/pN` maps onto the position `pN` of the file `<runId>.jsonl`.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const RUG_PCT = -80;
+export const MIN_CLOSED = 20;
+export const STUCK_WRITE_OFF_MIN = 30;
+const DAY = 86_400_000;
+/** mulberry32: the seeded generator of control/mine.mjs (same seed, same intervals). */
+export function rng(seed = 7) {
+    let a = seed >>> 0;
+    return () => { a = (a + 0x6d2b79f5) >>> 0; let t = a; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+const mean = (xs) => xs.reduce((s, x) => s + x, 0) / xs.length;
+const pctile = (xs, p) => { const s = [...xs].sort((a, b) => a - b); return s[Math.min(s.length - 1, Math.max(0, Math.floor(p * s.length)))]; };
+/** Mean with a 95% percentile-bootstrap interval (control/mine.mjs meanCi). */
+export function meanCi(xs, { B = 4000, seed = 7 } = {}) {
+    if (!xs.length)
+        return { n: 0, mean: null, lo: null, hi: null };
+    const r = rng(seed);
+    const ms = [];
+    for (let b = 0; b < B; b++) {
+        let s = 0;
+        for (let i = 0; i < xs.length; i++)
+            s += xs[Math.floor(r() * xs.length)];
+        ms.push(s / xs.length);
+    }
+    return { n: xs.length, mean: mean(xs), lo: pctile(ms, 0.025), hi: pctile(ms, 0.975) };
+}
+/** Difference of means (a - b), independent groups, bootstrap 95% (control/mine.mjs diffCi). */
+export function diffCi(a, b, { B = 4000, seed = 11 } = {}) {
+    if (!a.length || !b.length)
+        return { mean: null, lo: null, hi: null };
+    const r = rng(seed);
+    const ds = [];
+    for (let k = 0; k < B; k++) {
+        let sa = 0, sb = 0;
+        for (let i = 0; i < a.length; i++)
+            sa += a[Math.floor(r() * a.length)];
+        for (let i = 0; i < b.length; i++)
+            sb += b[Math.floor(r() * b.length)];
+        ds.push(sa / a.length - sb / b.length);
+    }
+    return { mean: mean(a) - mean(b), lo: pctile(ds, 0.025), hi: pctile(ds, 0.975) };
+}
+/** Wilson 95% interval for k of n, as fractions (control/mine.mjs wilson). */
+export function wilsonCi(k, n) {
+    if (!n)
+        return [null, null];
+    const z = 1.96, p = k / n, d = 1 + z * z / n, c = p + z * z / (2 * n), h = z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n));
+    return [Math.max(0, (c - h) / d), Math.min(1, (c + h) / d)];
+}
+/**
+ * Every strategy (fleet member) in one runs directory, its positions tracked across run files (control/report.mjs
+ * readMembers, rules in the header). `now` decides which stuck positions are already written off.
+ */
+export function readStrategyLedgers(runsDir, { now = Date.now(), writeOffMin = STUCK_WRITE_OFF_MIN } = {}) {
+    const M = {};
+    if (!existsSync(runsDir))
+        return M;
+    const symbols = new Map(); // mint -> symbol, from the candidate lines (fills carry no symbol)
+    const entryTick = new Map(); // mint -> the candidate tick that preceded the entry (pool age, liquidity, mcap)
+    const state = {};
+    const fin = (x) => typeof x === 'number' && Number.isFinite(x);
+    for (const f of readdirSync(runsDir).filter((x) => x.endsWith('.jsonl') && !/-fleet-/.test(x)).sort()) {
+        let member = null;
+        let text;
+        try {
+            text = readFileSync(join(runsDir, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line)
+                continue;
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (e.kind === 'fleet_member' || e.kind === 'run_start') {
+                member ??= e.member ?? e.strategy ?? null;
+                if (member && !M[member]) {
+                    M[member] = { files: 0, entries: 0, closed: [], open: 0, stuckOpen: [], openPositions: [], abandoned: [], writtenOff: [], adopted: 0, lastClampT: null, firstT: null, lastT: null, candidates: 0, entryTimes: [], startUsd: null, mode: null, basedOn: null };
+                    state[member] = { pos: new Map(), openNow: new Set(), closedKeys: new Set(), local: new Map(), file: null, carry: new Set() };
+                }
+                if (member) {
+                    const m = M[member];
+                    if (fin(e.bankroll?.usd) && m.startUsd === null)
+                        m.startUsd = e.bankroll.usd;
+                    m.mode ??= e.mode ?? null;
+                    if (e.basedOn)
+                        m.basedOn = e.basedOn;
+                    if (state[member].file !== f) {
+                        state[member].file = f;
+                        state[member].local = new Map();
+                        state[member].carry = new Set(state[member].openNow);
+                        m.files++;
+                    }
+                }
+                continue;
+            }
+            if (!member)
+                continue;
+            const m = M[member];
+            const s = state[member];
+            if (typeof e.t === 'number') {
+                m.firstT = m.firstT === null ? e.t : Math.min(m.firstT, e.t);
+                m.lastT = m.lastT === null ? e.t : Math.max(m.lastT, e.t);
+            }
+            // a restart adopts what it carries at the head of its file; a position of the previous (crashed) file it did not
+            // adopt is gone from the engine's book: "abandoned", not open forever
+            if (s.carry.size && e.kind !== 'position_adopted') {
+                for (const key of s.carry) {
+                    const p = s.pos.get(key);
+                    s.openNow.delete(key);
+                    m.abandoned.push({ positionId: p.positionId, mint: p.mint, openedT: p.firstT, stoppedT: e.t, notCarried: true, _p: p });
+                }
+                s.carry.clear();
+            }
+            if (e.kind === 'clamp' && typeof e.t === 'number')
+                m.lastClampT = Math.max(m.lastClampT ?? 0, e.t);
+            if (e.kind === 'candidate') {
+                m.candidates++;
+                if (e.mint && e.symbol)
+                    symbols.set(e.mint, e.symbol);
+                if (e.mint && e.tick)
+                    entryTick.set(e.mint, e.tick);
+                continue;
+            }
+            // the open position of an earlier file this id + mint carries (an adoption), newest first; `<runId>/pN` names the
+            // position pN of the file <runId>.jsonl exactly
+            const carried = (id, mint) => {
+                const slash = id.lastIndexOf('/');
+                if (slash > 0) {
+                    const k = `${id.slice(0, slash)}.jsonl#${id.slice(slash + 1)}`;
+                    if (s.pos.has(k) && !s.closedKeys.has(k))
+                        return k;
+                }
+                return [...s.openNow].reverse().find((k) => { const p = s.pos.get(k); return p.positionId === id && (!mint || !p.mint || p.mint === mint); }) ?? null;
+            };
+            const open = (id, mint, t, profile = null) => {
+                const key = `${f}#${id}`;
+                s.pos.set(key, { key, positionId: id, mint: mint ?? null, symbol: null, firstT: t, costUsd: 0, proceedsUsd: 0, stuckSince: null, stuckWhy: null, lastSellT: null, profile });
+                s.openNow.add(key);
+                s.local.set(id, key);
+                m.entries++;
+                if (t !== null)
+                    m.entryTimes.push(t);
+                return key;
+            };
+            const keyOf = (id, mint, t, { create = true, profile = null } = {}) => {
+                if (s.local.has(id))
+                    return s.local.get(id);
+                const c = carried(id, mint);
+                if (c) {
+                    s.local.set(id, c);
+                    return c;
+                }
+                return create ? open(id, mint, t, profile) : null;
+            };
+            if (e.kind === 'position_adopted' && e.positionId) {
+                const c = carried(e.positionId, e.mint);
+                const key = c ?? open(e.positionId, e.mint, e.position?.openedAt ?? e.t); // its fills were in a file that is gone: it counts here
+                s.carry.delete(key);
+                s.local.set(e.positionId, key);
+                m.adopted++;
+                const p = s.pos.get(key);
+                const snap = e.position ?? {};
+                if (!c && fin(snap.costUsd))
+                    p.costUsd = snap.costUsd;
+                if (snap.stuck && p.stuckSince === null)
+                    p.stuckSince = e.t;
+                p.symbol ??= e.symbol ?? null;
+                continue;
+            }
+            if (e.kind === 'fill' && e.positionId) {
+                const key = keyOf(e.positionId, e.mint, e.t, { profile: e.profile ?? null });
+                if (s.closedKeys.has(key))
+                    continue;
+                const p = s.pos.get(key);
+                p.profile ??= e.profile ?? null;
+                if (e.side === 'sell') {
+                    p.proceedsUsd += fin(e.usd) ? e.usd : 0;
+                    p.lastSellT = e.t;
+                    p.stuckSince = null;
+                    p.stuckWhy = null;
+                } // a sale ends a stuck spell
+                else
+                    p.costUsd += fin(e.usd) ? e.usd : 0;
+                continue;
+            }
+            if (e.kind === 'stuck' && e.positionId) {
+                const key = keyOf(e.positionId, e.mint, e.t, { create: false });
+                const p = key && s.pos.get(key);
+                if (p && p.stuckSince === null) {
+                    p.stuckSince = e.t;
+                    p.stuckWhy = `${e.reason ?? 'stuck'} (${e.why ?? 'cannot sell'})`;
+                }
+                continue;
+            }
+            if (e.kind === 'wake' && e.positionId && e.event === 'mechanical_exit') { // the engine's own words for the stuck exit
+                const key = s.local.get(e.positionId);
+                const p = key && s.pos.get(key);
+                if (p && p.stuckSince === e.t && e.detail)
+                    p.stuckWhy = e.detail;
+                continue;
+            }
+            if (e.kind === 'trade_closed' && e.trade) {
+                const key = keyOf(e.trade.id, e.trade.mint, e.trade.openedAt ?? e.t);
+                if (s.closedKeys.has(key))
+                    continue;
+                s.closedKeys.add(key);
+                s.openNow.delete(key);
+                const p = s.pos.get(key);
+                const tick = e.trade.mint ? entryTick.get(e.trade.mint) : undefined;
+                m.closed.push({ t: e.trade.closedAt ?? e.t, openedAt: e.trade.openedAt ?? null, mint: e.trade.mint ?? null, symbol: e.trade.symbol ?? null, pnlPct: e.trade.pnlPct, pnlUsd: e.trade.pnlUsd ?? null,
+                    costUsd: fin(e.trade.costUsd) ? e.trade.costUsd : p?.costUsd ?? null, exitReason: e.trade.exitReason ?? null, stuck: !!e.trade.stuck, profile: e.trade.profileId ?? p?.profile ?? null,
+                    entryAgeMin: fin(tick?.ageMin) ? tick.ageMin : null, entryLiqUsd: fin(tick?.liq) ? tick.liq : null, entryMcap: fin(tick?.mcap) ? tick.mcap : null });
+                continue;
+            }
+            if (e.kind === 'run_end') {
+                for (const key of s.openNow) {
+                    const p = s.pos.get(key);
+                    m.abandoned.push({ positionId: p.positionId, mint: p.mint, openedT: p.firstT, stoppedT: e.t, _p: p });
+                }
+                s.openNow.clear();
+            }
+        }
+    }
+    const writeOff = (m, p, endT, how) => {
+        const pnlUsd = Math.round((p.proceedsUsd - p.costUsd) * 1e4) / 1e4;
+        const pnlPct = p.costUsd > 0 ? Math.round((pnlUsd / p.costUsd) * 1e4) / 100 : null;
+        const tick = p.mint ? entryTick.get(p.mint) : undefined;
+        const w = { t: p.stuckSince, openedAt: p.firstT, mint: p.mint, symbol: p.symbol ?? (p.mint ? symbols.get(p.mint) ?? null : null), pnlPct, pnlUsd, costUsd: Math.round(p.costUsd * 1e4) / 1e4, realizedUsd: Math.round(p.proceedsUsd * 1e4) / 1e4,
+            exitReason: 'written-off', stuck: true, writtenOff: true, held: how === 'still held', profile: p.profile,
+            reason: `${how}: stuck ${Math.round((endT - p.stuckSince) / 60_000)} min with no sell (${p.stuckWhy ?? 'illiquid'}); unsold remainder valued 0`, stuckSince: p.stuckSince,
+            entryAgeMin: typeof tick?.ageMin === 'number' ? tick.ageMin : null, entryLiqUsd: typeof tick?.liq === 'number' ? tick.liq : null, entryMcap: typeof tick?.mcap === 'number' ? tick.mcap : null };
+        m.writtenOff.push(w);
+        if (pnlPct !== null)
+            m.closed.push(w);
+    };
+    for (const [id, m] of Object.entries(M)) {
+        const s = state[id];
+        m.abandoned = m.abandoned.filter((a) => { const p = a._p; delete a._p; if (p.stuckSince === null)
+            return true; writeOff(m, p, a.stoppedT ?? now, a.notCarried ? 'dropped stuck (not carried over by the restart)' : 'dropped stuck at a clean run end'); return false; });
+        for (const key of s.openNow) {
+            const p = s.pos.get(key);
+            if (p.stuckSince !== null && now - p.stuckSince >= writeOffMin * 60_000)
+                writeOff(m, p, now, 'still held');
+            else {
+                m.open++;
+                m.openPositions.push({ positionId: p.positionId, mint: p.mint, symbol: p.symbol ?? (p.mint ? symbols.get(p.mint) ?? null : null), openedAt: p.firstT, costUsd: Math.round(p.costUsd * 1e4) / 1e4, realizedUsd: Math.round(p.proceedsUsd * 1e4) / 1e4, stuckSince: p.stuckSince, profile: p.profile });
+                if (p.stuckSince !== null)
+                    m.stuckOpen.push({ positionId: p.positionId, mint: p.mint, stuckSince: p.stuckSince });
+            }
+        }
+        for (const c of m.closed)
+            c.symbol ??= c.mint ? symbols.get(c.mint) ?? null : null;
+        m.closed.sort((a, b) => a.t - b.t);
+    }
+    return M;
+}
+/**
+ * REALIZABLE value of an open position (agent-v4/scoreboard.mjs): the engine's mark sold into the pool with the
+ * engine's cost model (constant-product impact on half the liquidity, fee + slippage bps, network fee). null = the
+ * pool's liquidity is unknown.
+ */
+export function realizableUsd(markUsd, liqUsd, ex = { feeBps: 30, slippageBps: 200, networkFeeUsd: 0.02 }) {
+    if (!Number.isFinite(markUsd) || typeof liqUsd !== 'number' || !Number.isFinite(liqUsd) || liqUsd <= 0)
+        return null;
+    const side = liqUsd / 2;
+    const impact = markUsd / (side + markUsd);
+    return Math.max(0, markUsd * (1 - impact) * (1 - (ex.feeBps + ex.slippageBps) / 10_000) - ex.networkFeeUsd);
+}
+/** The realized equity curve over the closed sample (start + cumulative P/L in close order) and its drawdown from the running peak. */
+export function equityCurve(closed, startUsd) {
+    const start = startUsd ?? 100;
+    let eq = start;
+    let peak = start;
+    let maxDd = 0;
+    const points = [];
+    for (const c of [...closed].sort((a, b) => a.t - b.t)) {
+        eq += typeof c.pnlUsd === 'number' && Number.isFinite(c.pnlUsd) ? c.pnlUsd : 0;
+        peak = Math.max(peak, eq);
+        const dd = peak > 0 ? (1 - eq / peak) * 100 : 0;
+        maxDd = Math.max(maxDd, dd);
+        points.push({ t: c.t, usd: Math.round(eq * 100) / 100, drawdownPct: Math.round(dd * 10) / 10 });
+    }
+    return { points, maxDrawdownPct: Math.round(maxDd * 10) / 10, start, end: Math.round(eq * 100) / 100 };
+}
+/** One strategy's row (control/report.mjs summarize: rugs, means, ETA), plus the exits breakdown and the sample badge. */
+export function strategyRow(id, m, { now = Date.now(), minClosed = MIN_CLOSED } = {}) {
+    const xs = m.closed.map((c) => c.pnlPct).filter((x) => typeof x === 'number' && Number.isFinite(x));
+    const rugs = m.closed.filter((c) => (c.pnlPct ?? 0) <= RUG_PCT || (c.stuck && !c.writtenOff)).length;
+    const days = m.firstT === null ? 0 : (now - m.firstT) / DAY;
+    const perDay = days > 0 ? m.entries / days : null;
+    const ci = meanCi(xs);
+    const by = new Map();
+    for (const c of m.closed) {
+        const r = c.writtenOff ? 'written-off' : c.exitReason ?? 'unknown';
+        if (!by.has(r))
+            by.set(r, []);
+        if (typeof c.pnlPct === 'number')
+            by.get(r).push(c.pnlPct);
+    }
+    const exits = [...by].map(([reason, v]) => ({ reason, n: v.length, meanPct: v.length ? Math.round(mean(v) * 10) / 10 : null, wins: v.filter((x) => x > 0).length })).sort((a, b) => b.n - a.n);
+    const sample = xs.length === 0 ? 'none' : xs.length < minClosed ? 'exploratory' : 'minimum';
+    return {
+        id, entries: m.entries, closed: xs.length, open: m.open, writtenOff: m.writtenOff.length, stuckOpen: m.stuckOpen.length, abandoned: m.abandoned.length, adopted: m.adopted,
+        wins: xs.filter((x) => x > 0).length, losses: xs.filter((x) => x <= 0).length, rugs, rugRate: xs.length ? rugs / xs.length : null, rugCi: wilsonCi(rugs, xs.length),
+        meanPct: ci.mean, lo: ci.lo, hi: ci.hi, days, entriesPerDay: perDay, etaDays: perDay ? Math.max(0, (minClosed - xs.length) / perDay) : null,
+        sample, sampleText: sample === 'none' ? 'no closed trades yet' : sample === 'exploratory' ? `exploratory: ${xs.length} closed, < ${minClosed}` : `${xs.length} closed (>= ${minClosed})`,
+        realizedUsd: Math.round(m.closed.reduce((s, c) => s + (typeof c.pnlUsd === 'number' ? c.pnlUsd : 0), 0) * 100) / 100, exits,
+    };
+}
+/** The decision rule the control applies to a variant (control/report.mjs DECISION_RULE, baseline named). */
+export const decisionRule = (base, minClosed = MIN_CLOSED) => `A filter or exit change is adopted only if it beats ${base} over >= ${minClosed} closed entries in BOTH strategies with the 95% interval of the difference in mean % per entry clear of zero (above 0). Until then nothing changes.`;
+/** A variant against the baseline (control/report.mjs verdicts). */
+export function compareToBase(id, a, base, b, minClosed = MIN_CLOSED) {
+    const d = diffCi(a, b);
+    const enough = a.length >= minClosed && b.length >= minClosed;
+    const verdict = !enough ? `not yet: ${a.length} / ${b.length} closed (needs ${minClosed} each)` : (d.lo ?? 0) > 0 ? 'passes the rule: beats the baseline' : (d.hi ?? 0) < 0 ? 'worse than the baseline' : 'no clear difference: keep running';
+    return { id, base, n: a.length, baseN: b.length, diff: d, enough, verdict };
+}

package/dist/packages/autotrade/src/strategy.js

@@ -59,7 +59,7 @@ export const SCHEMAS = {
         kind: { type: 'string', enum: ['strategy'] },
         schema: { type: 'string', enum: [STRATEGY_SCHEMA] },
         id: str(32, ID), name: str(40), version: str(16, SEMVER), description: str(600),
-        mode: { type: 'string', enum: ['paper', 'live'] },
+        mode: { type: 'string', enum: ['paper', 'real', 'live'] },
         highRisk: { type: 'boolean' },
         bankroll: obj({ startUsd: num(1, 1e7), source: { type: 'string', enum: ['fixed', 'desk'] } }, ['startUsd']),
         entry: obj({
@@ -72,6 +72,13 @@ export const SCHEMAS = {
                 youngVertical: nullable(obj({ maxAgeHours: num(0, 168), maxH1Pct: num(0, 100000) })),
                 unknownHolders: { type: 'string', enum: ['reject', 'allow'] },
                 larp: nullable(obj({ maxScore: num(0, 100), unknown: { type: 'string', enum: ['reject', 'allow'] } })),
+                rugproof: nullable(obj({
+                    minPoolAgeMin: num(0, 1440), requireSafePool: { type: 'boolean' }, maxHolderLpPct: num(0, 100), maxWithdraws: num(0, 100, true), withdrawScanTx: num(1, 100, true),
+                    liquidityRecheck: nullable(obj({ afterSec: num(5, 600), floorX: num(1, 100), maxDropPct: num(0, 90) })),
+                    routeX: nullable(num(1, 20)),
+                    youngPool: nullable(obj({ underMin: num(1, 1440), maxSizePct: num(1, 100) })),
+                    drainGuard: nullable(obj({ pollSec: num(2, 10), liqDropPct: num(5, 90), exitOnNoRoute: { type: 'boolean' }, minReserveSol: num(0, 1000) })),
+                })),
             }, ['maxTop10Pct', 'maxDevPct', 'requireNoMintAuthority', 'requireNoFreezeAuthority', 'maxMcapSplitX', 'youngVertical', 'unknownHolders']),
             triggers: { type: 'array', max: 8, items: 'trigger' },
             triggerMode: { type: 'string', enum: ['any', 'all'] },
@@ -103,7 +110,7 @@ export const SCHEMAS = {
             onTimeout: { type: 'string', enum: ['skip'] },
             respawnOnWake: { type: 'boolean' },
         }, ['model', 'maxSessions', 'budgetUsdPerSession', 'budgetUsdPerDay', 'maxTurns', 'deltaEverySec', 'decideWithinSec', 'sessionMaxMin', 'onTimeout']),
-        execution: obj({ slippageBps: num(0, 5000), feeBps: num(0, 1000), networkFeeUsd: num(0, 10), latencyMs: num(0, 120000), maxPriceImpactPct: num(0.1, 50), minExitLiquidityUsd: num(0, 1e7) }),
+        execution: obj({ slippageBps: num(0, 5000), feeBps: num(0, 1000), networkFeeUsd: num(0, 10), latencyMs: num(0, 120000), maxPriceImpactPct: num(0.1, 50), minExitLiquidityUsd: num(0, 1e7), stuckWriteOffMin: nullable(num(1, 10080)) }, ['slippageBps', 'feeBps', 'networkFeeUsd', 'latencyMs', 'maxPriceImpactPct', 'minExitLiquidityUsd']),
         notes: { type: 'array', max: 8, items: str(300) },
     }, ['kind', 'schema', 'id', 'name', 'version', 'description', 'mode', 'bankroll', 'entry', 'exits', 'sizing', 'risk', 'agent', 'execution']),
 };
@@ -200,6 +207,8 @@ export function validateStrategy(doc, library = builtinProfiles()) {
         errors.push({ path: '/risk/drawdown', msg: 'sizeDownAtPct must not exceed haltAtPct' });
     if (r.drawdown.recoverBelowPct >= r.drawdown.sizeDownAtPct)
         errors.push({ path: '/risk/drawdown/recoverBelowPct', msg: 'recoverBelowPct must be below sizeDownAtPct' });
+    if (s.execution.stuckWriteOffMin != null && s.mode !== 'paper')
+        errors.push({ path: '/execution/stuckWriteOffMin', msg: `the stuck write-off is paper only: in mode ${s.mode} the bag is still in your wallet and keeps its exit signals (remove it or set it to null)` });
     if (s.agent.budgetUsdPerSession > s.agent.budgetUsdPerDay)
         errors.push({ path: '/agent/budgetUsdPerSession', msg: 'a session budget above the daily budget' });
     if (s.entry.ageHours.max !== null && s.entry.ageHours.max < s.entry.ageHours.min)
@@ -211,8 +220,12 @@ export function validateStrategy(doc, library = builtinProfiles()) {
             warnings.push({ path: `/entry/triggers/${i}`, msg: `${t.kind} triggers need the live ${t.kind} feed; replays and backtests treat them as not firing` });
     if (s.bankroll.source === 'desk')
         warnings.push({ path: '/bankroll/source', msg: 'desk reads the paper desk book during a run; backtests use startUsd' });
+    if (s.entry.safety.rugproof)
+        warnings.push({ path: '/entry/safety/rugproof', msg: 'the rug-proof chain and route gates (pool structure, LP, withdraw history, sell route) and the drain poller need live data; a replay evaluates only the tick gates and the pump.fun-mint proxy' });
     if (s.entry.safety.larp)
         warnings.push({ path: '/entry/safety/larp', msg: 'the LARP gate needs the live web (live data runs only); replays and backtests do not evaluate it' });
+    if (s.mode === 'real')
+        warnings.push({ path: '/mode', msg: 'mode real sends a LIVE TRADE FIRE signal for every trade to your own executor; it runs only after `dexterm autotrade signal arm` on your own terminal, at this exact version' });
     if (s.mode === 'live')
         warnings.push({ path: '/mode', msg: 'mode live does not run: dexterm runs strategies on paper only (it holds no key and places no live order); live trading happens in the Telegram trading bot of your choice' });
     if (errors.length)

package/dist/packages/autotrade/src/trade-ledger.js

@@ -9,7 +9,7 @@
 //
 // Where each ledger field comes from:
 //   strategy           run_start: strategy id, version and strategyHash
-//   wallet mode        run_start.mode (paper; a live run's executor name says devnet or mainnet)
+//   wallet mode        run_start.mode (paper; real = a real-mode run, task-1655; a live run's executor name says devnet or mainnet)
 //   profile            the entry fill's profile; 'structured' when the agent's DECISION named it, else 'default'
 //                      (the strategy's default profile), 'rule' for a mechanical (auto) entry
 //   entry reason       the agent's DECISION {"action":"enter","reason":…} of the session that entered (structured)
@@ -70,7 +70,7 @@ export function importRunLedger(path, runId) {
     const start = events.find((e) => e.kind === 'run_start') ?? null;
     const strategy = start && str(start.strategy) ? { id: String(start.strategy), version: str(start.version), hash: str(start.strategyHash) } : null;
     const executor = String(start?.executor ?? '');
-    const walletMode = start?.mode === 'live' ? (/mainnet/.test(executor) ? 'live' : 'devnet') : 'paper';
+    const walletMode = start?.mode === 'real' ? 'real' : start?.mode === 'live' ? (/mainnet/.test(executor) ? 'live' : 'devnet') : 'paper';
     const auto = start?.decide === 'auto';
     // task-1538: a parallel-run strategy on a shared paper account names it in its first line (and run_start).
     const memberLine = events.find((e) => e.kind === 'fleet_member') ?? null;