dexterm-cli 0.1.7 → 0.2.0

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

@@ -0,0 +1,330 @@
+// dexterm autotrade — trade-fire receipts, drift and the read-only wallet reconcile (task-1645, 0.2.0 card A).
+//
+// The user's executor reports what it did with a signal, as DATA only: `dexterm autotrade receipt …`, or by
+// appending a `dexterm-trade-receipt/1` line to $DEXTERM_HOME/autotrade/real/receipts.jsonl itself.
+//   status executed | rejected | failed, optional fill {priceUsd, sizeSol, tokens, txSig}, a short reason
+// A receipt never makes dexterm do anything: it only moves a real-mode position from `unconfirmed` to
+// executed / rejected / failed in the ledger, the Q screen and `autotrade audit`, and measures the drift between
+// what was signalled and what was filled. Exits keep firing on the monitor's own (paper-model) view regardless.
+//
+// The wallet reconcile reads a PUBLIC address the user supplies (SOL balance and token holdings, two read-only RPC
+// methods on an allowlist) and lists the mints dexterm thinks are held that the wallet does not show, and back.
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { realDir } from "./outbox.js";
+import { ACCOUNT_ID_RE } from "./signal.js";
+export const RECEIPT_SCHEMA = 'dexterm-trade-receipt/1';
+export const RECEIPT_STATUSES = ['executed', 'rejected', 'failed'];
+export const receiptsPath = (home) => join(realDir(home), 'receipts.jsonl');
+const TX_SIG = /^[1-9A-HJ-NP-Za-km-z]{64,90}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const pos = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null);
+/** Free text from an executor is data: printable ASCII only, 120 chars. */
+const text = (v, max) => { if (typeof v !== 'string')
+    return null; const t = v.replace(/[^\x20-\x7e]/g, '').trim().slice(0, max); return t || null; };
+export function validateReceipt(x) {
+    const r = x;
+    if (!r || typeof r !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (r.schema !== RECEIPT_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (typeof r.signalId !== 'string' || !HEX32.test(r.signalId))
+        return { ok: false, error: 'signalId' };
+    if (!Number.isSafeInteger(r.nonce) || r.nonce < 1)
+        return { ok: false, error: 'nonce' };
+    if (typeof r.accountId !== 'string' || !ACCOUNT_ID_RE.test(r.accountId))
+        return { ok: false, error: 'accountId' };
+    if (!RECEIPT_STATUSES.includes(r.status))
+        return { ok: false, error: 'status' };
+    if (typeof r.at !== 'number' || !Number.isFinite(r.at))
+        return { ok: false, error: 'at' };
+    let fill = null;
+    if (r.fill !== undefined && r.fill !== null) {
+        const f = r.fill;
+        if (typeof f !== 'object')
+            return { ok: false, error: 'fill' };
+        if (f.txSig !== undefined && f.txSig !== null && (typeof f.txSig !== 'string' || !TX_SIG.test(f.txSig)))
+            return { ok: false, error: 'fill.txSig is not a base58 signature' };
+        for (const k of ['priceUsd', 'sizeSol', 'tokens'])
+            if (f[k] !== undefined && f[k] !== null && pos(f[k]) === null)
+                return { ok: false, error: `fill.${k}` };
+        fill = { priceUsd: pos(f.priceUsd), sizeSol: pos(f.sizeSol), tokens: pos(f.tokens), txSig: typeof f.txSig === 'string' ? f.txSig : null };
+    }
+    if (r.status !== 'executed' && fill && (fill.sizeSol || fill.tokens))
+        return { ok: false, error: 'only an executed receipt carries a fill size' };
+    return { ok: true, receipt: { schema: RECEIPT_SCHEMA, signalId: r.signalId, nonce: r.nonce, accountId: r.accountId, status: r.status, at: r.at, fill, reason: text(r.reason, 120), executor: text(r.executor, 32) } };
+}
+export function appendReceipt(home, r) {
+    const v = validateReceipt(r);
+    if (!v.ok)
+        throw new Error(`receipt: ${v.error}`);
+    mkdirSync(realDir(home), { recursive: true, mode: 0o700 });
+    const fd = openSync(receiptsPath(home), 'a', 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(v.receipt)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Why a receipt does not belong to a known signal (or null): unknown nonce, another account, an id mismatch. */
+export function receiptMismatch(r, s) {
+    if (!s)
+        return 'unknown-signal';
+    if (s.id !== r.signalId)
+        return 'signal-id-mismatch';
+    if (s.accountId !== r.accountId)
+        return 'wrong-account';
+    // task-1654: a receipt for a `signal test` proves the round trip (signal test reports it); it is not an orphan.
+    if (s.type === 'test')
+        return 'test-signal';
+    if (s.type !== 'trade')
+        return 'not-a-trade-signal';
+    return null;
+}
+/**
+ * Reads receipts.jsonl incrementally (byte offset). Every valid receipt for a known signal is returned once; the
+ * rest are counted (`invalid`, `orphan`) and never acted on. A partial last line waits for its newline.
+ */
+export class ReceiptsTail {
+    offset = 0;
+    carry = '';
+    invalid = 0;
+    orphan = 0;
+    path;
+    lookup;
+    constructor(home, lookup) { this.path = receiptsPath(home); this.lookup = lookup; }
+    poll() {
+        if (!existsSync(this.path))
+            return [];
+        const size = statSync(this.path).size;
+        if (size < this.offset) {
+            this.offset = 0;
+            this.carry = '';
+        } // truncated: read again
+        if (size === this.offset)
+            return [];
+        const fd = openSync(this.path, 'r');
+        const buf = Buffer.alloc(Math.min(size - this.offset, 4 << 20));
+        let n = 0;
+        try {
+            n = readSync(fd, buf, 0, buf.length, this.offset);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.offset += n;
+        const chunk = this.carry + buf.subarray(0, n).toString('utf8');
+        const lines = chunk.split('\n');
+        this.carry = lines.pop() ?? '';
+        const out = [];
+        for (const l of lines) {
+            if (!l.trim())
+                continue;
+            let raw;
+            try {
+                raw = JSON.parse(l);
+            }
+            catch {
+                this.invalid++;
+                continue;
+            }
+            const v = validateReceipt(raw);
+            if (!v.ok) {
+                this.invalid++;
+                continue;
+            }
+            const mm = receiptMismatch(v.receipt, this.lookup(v.receipt.nonce));
+            if (mm === 'test-signal')
+                continue;
+            if (mm) {
+                this.orphan++;
+                continue;
+            }
+            out.push(v.receipt);
+        }
+        return out;
+    }
+}
+export function readReceipts(home) {
+    const p = receiptsPath(home);
+    if (!existsSync(p))
+        return { receipts: [], invalid: 0 };
+    const out = [];
+    let invalid = 0;
+    for (const l of readFileSync(p, 'utf8').split('\n')) {
+        if (!l.trim())
+            continue;
+        try {
+            const v = validateReceipt(JSON.parse(l));
+            if (v.ok)
+                out.push(v.receipt);
+            else
+                invalid++;
+        }
+        catch {
+            invalid++;
+        }
+    }
+    return { receipts: out, invalid };
+}
+const r1 = (v) => Math.round(v * 10) / 10;
+/** Signals vs receipts: one row per trade signal. */
+export function driftReport(signals, receipts, now, tolPct = 5) {
+    const trades = signals.filter((s) => s.type === 'trade');
+    const byNonce = new Map();
+    let orphanReceipts = 0;
+    const known = new Map(trades.map((s) => [s.nonce, s]));
+    const tests = new Set(signals.filter((s) => s.type === 'test').map((s) => s.nonce));
+    for (const r of receipts) {
+        if (tests.has(r.nonce))
+            continue;
+        if (receiptMismatch(r, known.get(r.nonce))) {
+            orphanReceipts++;
+            continue;
+        }
+        const l = byNonce.get(r.nonce) ?? [];
+        l.push(r);
+        byNonce.set(r.nonce, l);
+    }
+    const counts = { unconfirmed: 0, executed: 0, rejected: 0, failed: 0, 'expired-unconfirmed': 0 };
+    let sizeDrift = 0;
+    const rows = trades.map((s) => {
+        const rs = (byNonce.get(s.nonce) ?? []).sort((a, b) => a.at - b.at);
+        const last = rs[rs.length - 1];
+        const state = last ? last.status : now > s.expiresAt ? 'expired-unconfirmed' : 'unconfirmed';
+        counts[state]++;
+        const filled = last?.status === 'executed' ? last.fill?.sizeSol ?? null : null;
+        const sizeDriftPct = filled !== null && s.sizeSol > 0 ? r1(((filled - s.sizeSol) / s.sizeSol) * 100) : null;
+        const px = last?.status === 'executed' ? last.fill?.priceUsd ?? null : null;
+        const priceDriftPct = px !== null && s.price.usd ? r1(((px - s.price.usd) / s.price.usd) * 100) : null;
+        if (sizeDriftPct !== null && Math.abs(sizeDriftPct) > tolPct)
+            sizeDrift++;
+        return {
+            nonce: s.nonce, id: s.id, runId: s.runId, side: s.side, mint: s.mint, symbol: s.symbol, issuedAt: s.issuedAt, state, signalSol: s.sizeSol, filledSol: filled, sizeDriftPct, priceDriftPct,
+            txSig: last?.fill?.txSig ?? null, conflict: new Set(rs.map((r) => r.status)).size > 1, reason: last?.reason ?? null,
+        };
+    });
+    return { rows, counts, unconfirmed: counts.unconfirmed + counts['expired-unconfirmed'], sizeDrift, orphanReceipts };
+}
+const r2 = (v) => Math.round(v * 100) / 100;
+/** One receipt against its trade signal (null for anything that is not a known trade signal). */
+export function divergenceOf(s, r) {
+    if (!s || s.type !== 'trade' || receiptMismatch(r, s))
+        return null;
+    const f = r.status === 'executed' ? r.fill : null;
+    const px = f?.priceUsd ?? (f?.sizeSol && f.tokens ? (f.sizeSol * s.price.solUsd) / f.tokens : null);
+    const adverse = (ref) => (px && ref && ref > 0 ? r2(((s.side === 'buy' ? px - ref : ref - px) / ref) * 100) : null);
+    const modelTokens = s.model?.tokens ?? null;
+    const fillRatio = !f ? null : s.side === 'buy' ? (f.sizeSol && s.sizeSol > 0 ? Math.round((f.sizeSol / s.sizeSol) * 1000) / 1000 : null) : (f.tokens && modelTokens ? Math.round((f.tokens / modelTokens) * 1000) / 1000 : null);
+    return {
+        nonce: s.nonce, side: s.side, status: r.status, slippageVsPaperPct: adverse(s.model?.priceUsd ?? null), slippageVsQuotePct: adverse(s.price.usd),
+        latencyMs: Math.max(0, r.at - s.issuedAt), fillRatio, partial: fillRatio !== null && fillRatio < 0.95, reason: r.reason,
+    };
+}
+const quantile = (xs, q) => { if (!xs.length)
+    return null; const a = [...xs].sort((x, y) => x - y); return a[Math.min(a.length - 1, Math.floor(q * a.length))]; };
+/** Every trade signal's newest receipt, summarized. */
+export function divergenceReport(signals, receipts) {
+    const bySig = new Map(signals.filter((s) => s.type === 'trade').map((s) => [s.nonce, s]));
+    const newest = new Map();
+    for (const r of receipts) {
+        const s = bySig.get(r.nonce);
+        if (!s || receiptMismatch(r, s))
+            continue;
+        const p = newest.get(r.nonce);
+        if (!p || r.at >= p.at)
+            newest.set(r.nonce, r);
+    }
+    const rows = [...newest.values()].map((r) => divergenceOf(bySig.get(r.nonce), r)).filter((d) => !!d).sort((a, b) => a.nonce - b.nonce);
+    const ex = rows.filter((d) => d.status === 'executed');
+    const sl = ex.map((d) => d.slippageVsPaperPct ?? d.slippageVsQuotePct).filter((v) => v !== null);
+    const lat = rows.map((d) => d.latencyMs);
+    const reasons = {};
+    for (const d of rows)
+        if (d.status !== 'executed') {
+            const k = `${d.status}: ${(d.reason ?? 'no reason').slice(0, 40)}`;
+            reasons[k] = (reasons[k] ?? 0) + 1;
+        }
+    const n = ex.length;
+    return {
+        rows, trades: bySig.size, receipted: rows.length, executed: n, rejected: rows.filter((d) => d.status === 'rejected').length, failed: rows.filter((d) => d.status === 'failed').length, partial: rows.filter((d) => d.partial).length,
+        slippage: { n: sl.length, medianPct: quantile(sl, 0.5), p90Pct: quantile(sl, 0.9), meanPct: sl.length ? r2(sl.reduce((a, b) => a + b, 0) / sl.length) : null },
+        latency: { n: lat.length, medianMs: quantile(lat, 0.5), p90Ms: quantile(lat, 0.9) },
+        reasons,
+        note: n === 0 ? 'no executed receipt yet: nothing to compare paper with' : n < 30 ? `only ${n} executed fill(s): too few to calibrate paper fills with confidence` : `${n} executed fills`,
+    };
+}
+export function divergenceLines(d) {
+    const out = [`paper vs real: ${d.receipted}/${d.trades} trade signals have a receipt · executed ${d.executed} · rejected ${d.rejected} · failed ${d.failed} · partial ${d.partial}`];
+    if (d.slippage.n)
+        out.push(`  slippage vs paper fill: median ${d.slippage.medianPct}% · p90 ${d.slippage.p90Pct}% · mean ${d.slippage.meanPct}% (positive = the real fill was worse than paper)`);
+    if (d.latency.n)
+        out.push(`  latency signal -> receipt: median ${Math.round((d.latency.medianMs ?? 0) / 100) / 10} s · p90 ${Math.round((d.latency.p90Ms ?? 0) / 100) / 10} s`);
+    for (const [k, v] of Object.entries(d.reasons).slice(0, 5))
+        out.push(`  ${v}× ${k}`);
+    out.push(`  ${d.note}`);
+    return out;
+}
+// ───────────────────────────── read-only wallet reconcile ─────────────────────────────
+/** The only RPC methods the reconcile may call. Anything else is refused before it leaves the process. */
+export const RECONCILE_RPC_METHODS = ['getBalance', 'getTokenAccountsByOwner'];
+const TOKEN_PROGRAMS = ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'];
+const PUBKEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** Read a public wallet (balance + token holdings) and compare with the mints the real-mode book holds / closed. */
+export async function reconcileWallet(wallet, rpc, book) {
+    if (!PUBKEY.test(wallet))
+        throw new Error('reconcile: the wallet is a public base58 address (never a key)');
+    const call = (m, p) => { if (!RECONCILE_RPC_METHODS.includes(m))
+        return Promise.reject(new Error(`rpc method ${m} is not on the read-only allowlist`)); return rpc(m, p); };
+    const errors = [];
+    let sol = null;
+    try {
+        const b = (await call('getBalance', [wallet, { commitment: 'confirmed' }]));
+        sol = typeof b?.value === 'number' ? b.value / 1e9 : null;
+    }
+    catch (e) {
+        errors.push(`getBalance: ${e.message.slice(0, 120)}`);
+    }
+    const holdings = {};
+    for (const programId of TOKEN_PROGRAMS) {
+        try {
+            const r = (await call('getTokenAccountsByOwner', [wallet, { programId }, { encoding: 'jsonParsed', commitment: 'confirmed' }]));
+            for (const a of r?.value ?? []) {
+                const info = a.account?.data?.parsed?.info;
+                if (!info?.mint || !PUBKEY.test(info.mint))
+                    continue;
+                holdings[info.mint] = (holdings[info.mint] ?? 0) + (Number(info.tokenAmount?.uiAmount) || 0);
+            }
+        }
+        catch (e) {
+            errors.push(`getTokenAccountsByOwner: ${e.message.slice(0, 120)}`);
+        }
+    }
+    const ok = errors.length === 0;
+    return {
+        wallet, sol, holdings,
+        missing: ok ? book.held.filter((m) => !(holdings[m] > 0)) : [],
+        stillHeld: ok ? book.closed.filter((m) => holdings[m] > 0 && !book.held.includes(m)) : [],
+        errors,
+    };
+}
+/** From the trade signals alone (nonce order): the mints a real-mode book holds, and those it closed. */
+export function heldFromSignals(signals) {
+    const held = new Set();
+    const closed = new Set();
+    for (const s of [...signals].sort((a, b) => a.nonce - b.nonce)) {
+        if (s.type !== 'trade')
+            continue;
+        if (s.side === 'buy') {
+            held.add(s.mint);
+            closed.delete(s.mint);
+        }
+        else if ((s.sellFraction ?? 1) >= 0.999) {
+            held.delete(s.mint);
+            closed.add(s.mint);
+        }
+    }
+    return { held: [...held], closed: [...closed] };
+}

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

@@ -0,0 +1,168 @@
+// dexterm autotrade — the daily / weekly digest (task-1654, 0.2.0 card E). Read-only over the run ledgers.
+//
+// Per strategy and mode (paper | real) over a period: closed trades, the win rate with its 95% interval (Wilson),
+// net PnL, the max drawdown of the closed-trade curve, refusals, the limits that were hit, and for real mode the
+// executor's health and the paper-vs-real fill divergence from receipts. Every digest ends with an honest sample
+// note: a handful of trades says almost nothing, and the interval shows how little.
+//
+// `dexterm autotrade report` prints it (or --json, or --telegram through the user's own bot). A run with the
+// Telegram bot on sends it by itself when the user turned a schedule on (`report --schedule daily|weekly|off`,
+// saved in $DEXTERM_HOME/autotrade/digest.json; off by default).
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLedgerFile, runsDir, writeJsonAtomic } from "./ledger.js";
+import { localDay } from "./chat/audit.js";
+import { allOutboxSignals } from "./outbox.js";
+import { divergenceReport, readReceipts } from "./receipts.js";
+const r2 = (v) => Math.round(v * 100) / 100;
+/** The 95% Wilson score interval of k wins in n, in %. */
+export function wilson(k, n, z = 1.96) {
+    if (n <= 0)
+        return null;
+    const p = k / n;
+    const d = 1 + (z * z) / n;
+    const c = (p + (z * z) / (2 * n)) / d;
+    const h = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / d;
+    return [Math.round(Math.max(0, c - h) * 1000) / 10, Math.round(Math.min(1, c + h) * 1000) / 10];
+}
+export function periodBounds(period, now) {
+    return { from: now - (period === 'day' ? 1 : 7) * 86_400_000, to: now };
+}
+/** The digest of every run ledger with events in [from, to]. */
+export function buildDigest(home, o) {
+    const b = periodBounds(o.period, o.now);
+    const from = o.from ?? b.from;
+    const to = o.to ?? b.to;
+    const by = new Map();
+    const dir = runsDir(home);
+    const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.jsonl')) : [];
+    let anyReal = false;
+    for (const f of files) {
+        let ev;
+        try {
+            ev = readLedgerFile(join(dir, f));
+        }
+        catch {
+            continue;
+        }
+        const start = ev.find((e) => e.kind === 'run_start');
+        if (!start || typeof start.strategy !== 'string')
+            continue;
+        if (o.strategyId && start.strategy !== o.strategyId)
+            continue;
+        const inPeriod = ev.filter((e) => e.t >= from && e.t <= to);
+        if (!inPeriod.length)
+            continue;
+        const mode = start.mode === 'real' || start.tag === 'real-signal' ? 'real' : 'paper';
+        if (mode === 'real')
+            anyReal = true;
+        const key = `${start.strategy}|${mode}`;
+        let d = by.get(key);
+        if (!d) {
+            d = { strategyId: start.strategy, mode, runs: 0, trades: 0, wins: 0, winRatePct: null, winRateCi: null, netUsd: 0, maxDrawdownUsd: 0, refusals: 0, limitsHit: {}, clamped: {}, receipts: 0, closes: [] };
+            by.set(key, d);
+        }
+        d.runs++;
+        for (const e of inPeriod) {
+            if (e.kind === 'trade_closed') {
+                const pnl = Number(e.trade?.pnlUsd);
+                if (Number.isFinite(pnl)) {
+                    d.trades++;
+                    if (pnl > 0)
+                        d.wins++;
+                    d.netUsd += pnl;
+                    d.closes.push({ t: e.t, pnl });
+                }
+            }
+            else if (e.kind === 'refused') {
+                d.refusals++;
+                const rule = String(e.rule ?? '');
+                const m = /^(?:fill-)?(real-[a-z-]+)/.exec(rule);
+                if (m)
+                    d.limitsHit[m[1]] = (d.limitsHit[m[1]] ?? 0) + 1;
+            }
+            else if (e.kind === 'fill' && Array.isArray(e.limitClamps)) {
+                for (const c of e.limitClamps)
+                    d.clamped[c] = (d.clamped[c] ?? 0) + 1;
+            }
+            else if (e.kind === 'receipt')
+                d.receipts++;
+        }
+    }
+    const strategies = [...by.values()].map(({ closes, ...d }) => {
+        closes.sort((a, b2) => a.t - b2.t);
+        let cum = 0;
+        let peak = 0;
+        let dd = 0;
+        for (const c of closes) {
+            cum += c.pnl;
+            peak = Math.max(peak, cum);
+            dd = Math.max(dd, peak - cum);
+        }
+        return { ...d, netUsd: r2(d.netUsd), maxDrawdownUsd: r2(dd), winRatePct: d.trades ? Math.round((d.wins / d.trades) * 1000) / 10 : null, winRateCi: wilson(d.wins, d.trades) };
+    }).sort((a, b2) => a.strategyId.localeCompare(b2.strategyId) || a.mode.localeCompare(b2.mode));
+    let divergence = null;
+    if (anyReal) {
+        const sig = allOutboxSignals(home).filter((s) => s.issuedAt >= from && s.issuedAt <= to);
+        const d = divergenceReport(sig, readReceipts(home).receipts);
+        const { rows: _rows, ...rest } = d;
+        divergence = rest;
+    }
+    const n = strategies.reduce((a, s) => a + s.trades, 0);
+    const note = n === 0 ? 'no closed trades in this period'
+        : n < 30 ? `${n} closed trade(s) in total: a small sample. The win-rate intervals show how wide the truth may be; read no trend into it.`
+            : `${n} closed trades: still check the interval before trusting a win rate, and past results do not predict future ones`;
+    return { period: o.period, from, to, strategies, divergence, executor: o.executor ?? null, note };
+}
+const usd = (v) => `${v < 0 ? '-' : '+'}$${Math.abs(v).toFixed(2)}`;
+/** Plain lines (CLI and Telegram; no token text: strategy ids and engine numbers only). */
+export function digestLines(d) {
+    const out = [`dexterm ${d.period === 'day' ? 'daily' : 'weekly'} digest · ${new Date(d.from).toISOString().slice(0, 16).replace('T', ' ')} to ${new Date(d.to).toISOString().slice(0, 16).replace('T', ' ')} UTC · not financial advice`];
+    if (!d.strategies.length)
+        out.push('  no runs in this period');
+    for (const s of d.strategies) {
+        out.push(`${s.mode === 'real' ? 'REAL' : 'paper'} ${s.strategyId} · ${s.runs} run(s) · ${s.trades} trade(s)${s.trades ? ` · win ${s.winRatePct}% (95% interval ${s.winRateCi[0]}-${s.winRateCi[1]}%)` : ''} · net ${usd(s.netUsd)} · max drawdown $${s.maxDrawdownUsd.toFixed(2)}`);
+        const hit = Object.entries(s.limitsHit).map(([k, v]) => `${k} ×${v}`).join(', ');
+        const cl = Object.entries(s.clamped).map(([k, v]) => `${k} ×${v}`).join(', ');
+        out.push(`  refusals ${s.refusals}${hit ? ` · limits hit: ${hit}` : ''}${cl ? ` · clamped by: ${cl}` : ''}${s.mode === 'real' ? ` · receipts ${s.receipts}` : ''}`);
+    }
+    if (d.divergence) {
+        const v = d.divergence;
+        out.push(`paper vs real fills: ${v.receipted}/${v.trades} receipted · executed ${v.executed} · rejected ${v.rejected} · failed ${v.failed} · partial ${v.partial}${v.slippage.n ? ` · slippage vs paper median ${v.slippage.medianPct}% (p90 ${v.slippage.p90Pct}%)` : ''}${v.latency.n ? ` · latency median ${Math.round((v.latency.medianMs ?? 0) / 100) / 10} s` : ''}`);
+        out.push(`  ${v.note}`);
+    }
+    if (d.executor)
+        out.push(`executor: ${d.executor.alive === false ? 'SILENT' : d.executor.alive ? 'alive' : d.executor.lastSeenAt ? 'seen' : 'never seen'}${d.executor.silentSec !== null ? ` · last heard ${Math.round(d.executor.silentSec / 60)} min ago` : ''}${d.executor.lastReceipt ? ` · last receipt #${d.executor.lastReceipt.nonce} ${d.executor.lastReceipt.status}` : ''}`);
+    out.push(d.note);
+    return out;
+}
+// ───────────────────────────── the schedule (opt-in) ─────────────────────────────
+export const DIGEST_SCHEMA = 'dexterm-digest/1';
+export const digestStatePath = (home) => join(home, 'autotrade', 'digest.json');
+export function loadDigestState(home) {
+    try {
+        const d = JSON.parse(readFileSync(digestStatePath(home), 'utf8'));
+        if (d.schema === DIGEST_SCHEMA && ['off', 'daily', 'weekly'].includes(d.schedule))
+            return d;
+    }
+    catch { /* none */ }
+    return { schema: DIGEST_SCHEMA, schedule: 'off', lastSentDay: null, lastSentAt: null };
+}
+export function saveDigestState(home, s) {
+    mkdirSync(join(home, 'autotrade'), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(digestStatePath(home), s);
+}
+/**
+ * Is a scheduled digest due? Daily: once per local day, for the day before (first check after midnight). Weekly: on
+ * a Monday, for the week before. Never twice for the same day.
+ */
+export function digestDue(s, now) {
+    if (s.schedule === 'off')
+        return null;
+    const today = localDay(now);
+    if (s.lastSentDay === today)
+        return null;
+    if (s.schedule === 'weekly' && new Date(now).getDay() !== 1)
+        return null;
+    return s.schedule === 'daily' ? 'day' : 'week';
+}

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

@@ -12,7 +12,8 @@
 // never sleep (the source paces itself) and replies land when they land.
 //
 // Every step lands in the hash-chained run ledger (ledger.ts) with the exact inputs (the tick, the message text, the
-// raw reply, the clamp). Paper only: a strategy whose mode is not "paper" is refused before the first tick. The
+// raw reply, the clamp). Paper, or real (task-1645: the paper engine plus a trade-fire signal per fill, through the
+// real-mode hook only); any other mode is refused before the first tick. The
 // sessions' day caps and allowance guard live in SessionGate (sessions.ts); with none given, the strategy's own
 // limits apply; the gate counts real usage per wall-clock day, so a fast --replay over many tape days never resets
 // the $/day cap. The host part at the end of this file (lock, rendezvous, heartbeat) is what the CLI uses.
@@ -39,8 +40,16 @@ export async function runAutotrade(o) {
     const s = o.strategy;
     // task-1571: autotrade runs on paper only. dexterm holds no key and places no live order; live trading happens in the
     // Telegram trading bot of the user's choice.
-    if (s.mode !== 'paper')
-        throw new Error(`strategy ${s.id} is mode "${s.mode}": autotrade runs paper only (dexterm holds no key and places no live order)`);
+    // task-1645: mode "real" = the same paper engine, plus a LIVE TRADE FIRE signal per fill for the user's own executor;
+    // it needs the real-mode hook (armed on the user's terminal, checked by the host) and never runs without it.
+    if (s.mode === 'real' && !o.real)
+        throw new Error(`strategy ${s.id} is mode "real": it runs only through the real-mode host (dexterm autotrade run ${s.id} --real, once armed on your own terminal)`);
+    if (s.mode !== 'paper' && s.mode !== 'real')
+        throw new Error(`strategy ${s.id} is mode "${s.mode}": autotrade runs paper only (dexterm holds no key and places no live order); mode real runs only through the real-mode host`);
+    if (o.real && s.mode !== 'real')
+        throw new Error(`strategy ${s.id} is mode "${s.mode}": the real-mode hook is for a strategy in mode "real" only`);
+    if (o.real && (!o.executor || o.executor !== o.real))
+        throw new Error('real mode: the executor must be the real-mode signal executor itself');
     if (!o.tape && !o.source)
         throw new Error('runAutotrade needs a tape or a live source');
     const ledger = o.ledger ?? new Ledger();
@@ -86,7 +95,29 @@ export async function runAutotrade(o) {
     const pumps = new Set();
     /** Proposals waiting for an answer, by mint (task-1527). */
     const approvalsOpen = new Map();
-    ledger.add(t0, 'run_start', { strategy: s.id, version: s.version, strategyHash: s.hash, mode: s.mode, ...(s.highRisk ? { highRisk: true } : {}), tape: o.tape?.source ?? o.source.name, ticks: tapeTicks?.length ?? null, decide: decideAuto ? 'auto' : s.entry.decide, ...(o.approvals ? { approvals: o.approvals.required(s) ? 'required' : 'when-asked' } : {}), pacing: pacing.mode, executor: exec.name, caps: capsView(gate), ...(o.account ? { account: o.account.id } : {}) });
+    ledger.add(t0, 'run_start', { strategy: s.id, version: s.version, strategyHash: s.hash, mode: s.mode, ...(o.real ? { tag: 'real-signal', accountId: o.real.accountId } : {}), ...(s.highRisk ? { highRisk: true } : {}), tape: o.tape?.source ?? o.source.name, ticks: tapeTicks?.length ?? null, decide: decideAuto ? 'auto' : s.entry.decide, ...(o.approvals ? { approvals: o.approvals.required(s) ? 'required' : 'when-asked' } : {}), pacing: pacing.mode, executor: exec.name, caps: capsView(gate), ...(o.account ? { account: o.account.id } : {}) });
+    // task-1645 r2: a real run takes over the real positions an earlier run of this strategy left open (held.json),
+    // so their exits keep firing. A profile the strategy no longer has falls back to its default profile.
+    for (const p of o.real?.inherited() ?? []) {
+        const from = p.profileId;
+        if (!s.exits.profiles[p.profileId])
+            p.profileId = s.exits.default;
+        if (!book.adopt(p))
+            continue;
+        ledger.add(t0, 'position_adopted', { tag: 'real-signal', positionId: p.id, mint: p.mint, symbol: p.symbol, ...(from !== p.profileId ? { profileFrom: from } : {}), position: { ...p, fills: p.fills } });
+        say(`CARRIED ${p.symbol} (${p.mint.slice(0, 4)}…): real position from an earlier run, ${p.profileId}, cost $${(p.costUsd - p.realizedUsd).toFixed(2)} still open; its exits keep running`);
+    }
+    // 0.2.0 card B: positions a crashed run left open. A profile the (re-read) strategy no longer has falls back to
+    // its default profile, so every adopted position has exits.
+    for (const p of o.adopt ?? []) {
+        const from = p.profileId;
+        if (!s.exits.profiles[p.profileId])
+            p.profileId = s.exits.default;
+        if (!book.adopt(p))
+            continue;
+        ledger.add(t0, 'position_adopted', { positionId: p.id, mint: p.mint, symbol: p.symbol, ...(from !== p.profileId ? { profileFrom: from } : {}), position: { ...p, fills: p.fills } });
+        say(`RESUMED ${p.symbol} (${p.mint.slice(0, 4)}…): ${p.profileId}, cost $${(p.costUsd - p.realizedUsd).toFixed(2)} still open; its exits keep running`);
+    }
     const count = (rule) => { refusals[rule] = (refusals[rule] ?? 0) + 1; };
     const refuse = (rule, data) => { count(rule); ledger.add(now, 'refused', { rule, ...data }); };
     // A vet that throws or hangs is a check that could not run: the strategy's `unknown` decides (reject by default).
@@ -149,12 +180,12 @@ export async function runAutotrade(o) {
             return;
         }
         p.stuck = false;
-        ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), detail });
+        ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), detail, ...sigTag(f) });
         say(`SELL ${p.symbol} ${reason}: $${f.usd.toFixed(2)} at ${lvl(f.price, k)} (impact ${f.impactPct}%) — ${detail}`);
         const ct = book.sell(p, f);
         if (ct) {
             // task-1530: the price extremes the monitor saw while held (the trade ledger's MFE / MAE)
-            ledger.add(now, 'trade_closed', { trade: { ...ct, fills: undefined }, entryPrice: p.entryPrice, peakPrice: p.peakPrice, troughPrice: p.troughPrice ?? null });
+            ledger.add(now, 'trade_closed', { trade: { ...ct, fills: undefined }, entryPrice: p.entryPrice, peakPrice: p.peakPrice, troughPrice: p.troughPrice ?? null, ...(o.real ? { tag: 'real-signal' } : {}) });
             say(`CLOSED ${ct.symbol}: ${ct.pnlUsd >= 0 ? '+' : ''}$${ct.pnlUsd.toFixed(2)} (${ct.pnlPct}%) by ${ct.exitReason}`);
         }
     };
@@ -436,14 +467,14 @@ export async function runAutotrade(o) {
                 f.reason = 'ladder-add';
                 const bookUsd = round4(book.bookEquity()); // task-1530: the book before the fill (the trade ledger's % of book)
                 book.addTranche(p, f);
-                ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), bookUsd });
+                ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, ...fillMcaps(fillView(f), k), bookUsd, ...sigTag(f) });
                 say(`ADD ${k.symbol}: $${f.usd.toFixed(2)} at ${lvl(f.price, k)}`);
                 continue;
             }
             const prof = s.exits.profiles[q.profile];
             const bookUsd = round4(book.bookEquity()); // task-1530: the book before the fill (the trade ledger's % of book)
             const p = book.openPosition(k, f, prof, q.sessionId, q.trigger, q.ladder);
-            ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, profile: prof.id, ...fillMcaps(fillView(f), k), bookUsd, ...(q.ctx?.proposalId ? { proposalId: q.ctx.proposalId } : {}) });
+            ledger.add(now, 'fill', { positionId: p.id, mint: p.mint, profile: prof.id, ...fillMcaps(fillView(f), k), bookUsd, ...(q.ctx?.proposalId ? { proposalId: q.ctx.proposalId } : {}), ...sigTag(f) });
             say(`BUY ${k.symbol} [${prof.id}]: $${f.usd.toFixed(2)} at ${lvl(f.price, k)}${f.partial ? ' (PARTIAL: impact cap)' : ''} · liq $${Math.round(k.liq ?? 0)}`);
             const c = cands.get(q.mint);
             if (c) {
@@ -525,18 +556,25 @@ export async function runAutotrade(o) {
             sessions: live.map((c) => ({ id: c.session.id, kind: c.sessionKind, mint: c.mint, symbol: c.symbol, turns: c.turns, costUsd: round4(c.session.costUsd()), budgetUsd: gate.caps.budgetUsdPerSession, lastDecision: c.lastDecision })),
             positions: [...book.open.values()].map((p) => {
                 const pnl = liquidationMark(p) + p.realizedUsd - p.costUsd;
-                return { mint: p.mint, symbol: p.symbol, profile: p.profileId, costUsd: round2(p.costUsd), pnlUsd: round2(pnl), pnlPct: p.costUsd ? Math.round((pnl / p.costUsd) * 1000) / 10 : 0, next: p.stuck ? 'stuck: retried every tick' : null, ...(p.costRecovered ? { freeBag: true } : {}) };
+                return { mint: p.mint, symbol: p.symbol, profile: p.profileId, costUsd: round2(p.costUsd), pnlUsd: round2(pnl), pnlPct: p.costUsd ? Math.round((pnl / p.costUsd) * 1000) / 10 : 0, next: p.stuck ? 'stuck: retried every tick' : null, ...(p.costRecovered ? { freeBag: true } : {}), ...(o.real ? { confirm: o.real.confirmOf(p.mint) ?? 'unconfirmed' } : {}) };
             }),
             ledgerTail: ledger.events.slice(-12).map((e) => ({ seq: e.seq, t: e.t, kind: e.kind, text: tailText(e) })),
             ledgerHead: ledger.head(),
             events: ledger.events.length,
+            ...(o.real ? { real: o.real.status() } : {}),
         };
     };
     const loop = tapeTicks ? fromArray(tapeTicks) : o.source.ticks;
     for await (const k of loop) {
         now = k.t;
         const v = o.safety?.() ?? null;
-        const haltWhy = v?.halt ?? (o.killSwitch?.() ? 'kill-switch' : null);
+        // task-1645: receipts land in the ledger as data; the real-mode kill switch halts like the panic file.
+        const rs = o.real?.step() ?? null;
+        for (const r of rs?.receipts ?? []) {
+            const dv = r.divergence;
+            ledger.add(now, 'receipt', { tag: 'real-signal', nonce: r.nonce, signalId: r.signalId, status: r.status, fill: r.fill, reason: r.reason, executor: r.executor, ...(dv ? { divergence: dv } : {}) });
+        }
+        const haltWhy = v?.halt ?? (o.killSwitch?.() ? 'kill-switch' : null) ?? rs?.halt ?? null;
         if (!killed && haltWhy) {
             killed = true;
             haltReason = haltWhy;
@@ -609,7 +647,10 @@ export async function runAutotrade(o) {
             }
         }
         else if (pos) {
-            const prof = s.exits.profiles[pos.profileId];
+            const prof0 = s.exits.profiles[pos.profileId];
+            // task-1654: a real run's (or a paper scope's) maxHoldMinutes limit tightens the profile's holding cap (never loosens it).
+            const holdCap = o.real?.maxHoldMinutes?.() ?? o.maxHoldMinutes?.() ?? null;
+            const prof = holdCap !== null && (prof0.maxHoldMinutes == null || holdCap < prof0.maxHoldMinutes) ? { ...prof0, maxHoldMinutes: holdCap } : prof0;
             const acts = monitorTick(pos, prof, k, { minExitLiquidityUsd: x.minExitLiquidityUsd, sellUsd: (tok) => { const f = simSell(k, tok, x, 'estimate'); return 'refused' in f ? 0 : f.usd; } });
             const wakes = [];
             for (const a of acts) {
@@ -746,6 +787,14 @@ export async function runAutotrade(o) {
     while (pumps.size)
         await Promise.allSettled([...pumps]);
     const openAtEnd = [...book.open.values()].map((p) => ({ mint: p.mint, symbol: p.symbol, markUsd: round2(liquidationMark(p)), costUsd: p.costUsd, stuck: p.stuck }));
+    if (o.real) {
+        // The dead-man's graceful half: the executor hears the run is over (its outstanding nonces may be cancelled).
+        const why = killed ? `halt:${haltReason ?? 'kill'}` : o.tape ? 'end-of-tape' : 'runner-stopped';
+        // r2: what is still open is carried (held.json): the next real run of this strategy adopts it and keeps its exits.
+        o.real.carry([...book.open.values()]);
+        o.real.sendHalted(why);
+        ledger.add(now, 'real_halted', { tag: 'real-signal', reason: why, openAtEnd: openAtEnd.length });
+    }
     ledger.add(now, 'run_end', { trades: book.closed.length, openAtEnd: openAtEnd.length, cashUsd: book.state.cashUsd, markedEquityUsd: book.markedEquity(), sessionCostUsd: sessionCost, sessions: sessionsOpened, positionSessions: positionSessionsOpened, head: ledger.head() });
     publishFocus();
     if (o.onState)
@@ -772,6 +821,8 @@ export function exitPlanLine(p) {
     return `${p.id}: ${parts.join(', ')}`;
 }
 const round4 = (v) => Math.round(v * 1e4) / 1e4;
+/** task-1645: a fill that went out as a trade-fire signal: the ledger row is tagged and names the signal. */
+const sigTag = (f) => { const x = f; const g = x.signal; return g ? { tag: 'real-signal', nonce: g.nonce, signalId: g.id, ...(x.limitClamps?.length ? { limitClamps: x.limitClamps } : {}) } : {}; };
 const fillView = (f) => ({ side: f.side, usd: f.usd, tokens: Number(f.tokens.toPrecision(8)), price: f.price, avgPrice: f.avgPrice, impactPct: f.impactPct, partial: f.partial, reason: f.reason });
 /** Infinity (no runner cap) is written as null so the ledger stays JSON. */
 /** The model a session actually runs (a run's --model override wins over the strategy's), for the ledger. */