dexterm-cli 0.1.7 → 0.2.1

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';
+}