dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/cli/src/autotrade-cmd/limits.js

@@ -0,0 +1,393 @@
+// `dexterm autotrade limits …` (task-1654, 0.2.0 card E): every real-mode limit, user-set, per scope.
+//
+//   show      the effective limits (for a strategy / account / mode) and where each number comes from
+//   set       name=value … in a scope (global | real | paper | strategy:<id> | account:<id>); lowering is immediate,
+//             raising shows the old -> new diff and needs the typed phrase on a real terminal
+//   diff      a proposed file (--file) against the limits now, or limits.json against dexterm's last journaled save
+//   reset     a scope (or one --key) back to the placeholder defaults (a raise if that loosens anything: typed)
+//   accept    take a hand-edited limits.json (typed when it raises anything; a lower-only edit is accepted as is)
+//   breaker   `breaker reset`: lift a tripped drawdown breaker (typed)
+//   explain   what each limit does    schema  the JSON Schema of the file
+//
+// No MCP tool, model decision or chat command reaches the writing paths: the analyst can read and explain the limits
+// and propose a diff card (MCP limits_propose), which only YOU can apply here.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dextermHome } from '../../../custom/src/index.js';
+import { DEFAULT_LIMITS, LIMIT_FIELDS, LIMIT_KEYS, changeLine, diffLimits, effectiveLimits, emptyLimits, limitField, limitsLines, limitsPath, limitsSummary, loadArmings, loadLimits, loadRiskState, parseLimitAssignment, planLimitsSave, raises, resetBreaker, saveLimits, scopeRef, validateLimits, } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+import { confirmTyped, isTty, typedLine } from "./signal.js";
+export const LIMITS_USAGE = [
+    'dexterm autotrade limits show [--strategy ID] [--account ID] [--mode real|paper] [--all] [--json]',
+    'dexterm autotrade limits set [--scope global|real|paper|strategy:ID|account:ID] name=value … (value "off" turns a global limit off)',
+    'dexterm autotrade limits diff [--file FILE] [--json]',
+    'dexterm autotrade limits reset [--scope S] [--key NAME]',
+    'dexterm autotrade limits accept | breaker reset | explain [NAME] | schema',
+].join('\n');
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, s) => { io.stderr.write(`dexterm autotrade limits: ${s}\n`); };
+export const LIMITS_SCHEMA_FILE = fileURLToPath(new URL('../../../autotrade/assets/limits.schema.json', import.meta.url));
+export async function limitsCmd(argv, io, deps = {}) {
+    const home = dextermHome(io.env);
+    const now = deps.now ?? Date.now;
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case undefined:
+        case 'help':
+            out(io, LIMITS_USAGE);
+            return 0;
+        case 'show': return showCmd(rest, io, home, now);
+        case 'set': return setCmd(rest, io, home, deps, now);
+        case 'diff': return diffCmd(rest, io, home);
+        case 'reset': return resetCmd(rest, io, home, deps, now);
+        case 'accept': return acceptCmd(io, home, deps, now);
+        case 'breaker': {
+            if (rest[0] !== 'reset') {
+                err(io, 'usage: dexterm autotrade limits breaker reset');
+                return 2;
+            }
+            const r = loadRiskState(home, now());
+            if (!r.breaker) {
+                out(io, 'the drawdown breaker is not tripped');
+                return 0;
+            }
+            out(io, `the drawdown breaker tripped ${new Date(r.breaker.at).toISOString()} at ${r.breaker.drawdownSol} SOL below the peak; resetting it lets new real buys go out again (it also lifts a loss-streak pause and restarts the streak count)`);
+            const code = await confirmTyped(io, deps, 'RESET', 'breaker');
+            if (!code)
+                return 1;
+            const x = resetBreaker(home, { confirmed: true, now: now() });
+            if (!x.ok) {
+                err(io, x.why);
+                return 1;
+            }
+            out(io, 'drawdown breaker reset (journaled); the peak starts again from here; any loss-streak pause is lifted too');
+            return 0;
+        }
+        case 'explain': return explainCmd(rest, io);
+        case 'schema':
+            out(io, readFileSync(LIMITS_SCHEMA_FILE, 'utf8').trimEnd());
+            return 0;
+        default:
+            err(io, `unknown subcommand ${JSON.stringify(sub)}\n${LIMITS_USAGE}`);
+            return 2;
+    }
+}
+function current(home) {
+    const l = loadLimits(home);
+    if (l.ok)
+        return { doc: l.doc, ok: true, note: l.source === 'migrated' ? 'read from card A\'s caps.json (saved as limits.json on your next change)' : l.unjournaled ? `limits.json differs from dexterm's last save (${l.unjournaled.length} change(s)): dexterm autotrade limits diff` : null };
+    if (l.missing)
+        return { doc: emptyLimits(), ok: true, note: 'no limits saved yet: these are the placeholder defaults, NOT your numbers (real mode will not arm on them silently)' };
+    return { doc: emptyLimits(), ok: false, note: l.why };
+}
+function showCmd(argv, io, home, now) {
+    const { opts } = parseArgs(argv, ['json', 'all']);
+    const mode = opts.mode === 'paper' ? 'paper' : 'real';
+    const strategyId = typeof opts.strategy === 'string' ? opts.strategy : '-';
+    const accountId = typeof opts.account === 'string' ? opts.account : '-';
+    const c = current(home);
+    if (!c.ok) {
+        err(io, c.note ?? 'limits unreadable');
+        return 1;
+    }
+    const e = effectiveLimits(c.doc, { strategyId, accountId, mode });
+    const armed = Object.values(loadArmings(home)).map((a) => ({ id: a.strategyId, accountId: a.accountId, limits: effectiveLimits(c.doc, { strategyId: a.strategyId, accountId: a.accountId, mode: 'real' }).values }));
+    const risk = loadRiskState(home, now());
+    if (opts.json) {
+        out(io, JSON.stringify({ file: limitsPath(home), note: c.note, context: { mode, strategyId, accountId }, applies: e.applies, effective: e.values, from: e.from, scopes: c.doc, armed, risk: { day: risk.day, buys: risk.buys, buySol: risk.buySol, dayPnlSol: risk.dayPnlSol, cumPnlSol: risk.cumPnlSol, lossStreak: risk.lossStreak, pausedUntil: risk.pausedUntil, breaker: risk.breaker } }, null, 2));
+        return 0;
+    }
+    out(io, `real-mode limits (${limitsPath(home)}) · outside the model: only you change them, here · the defaults are placeholders, your numbers win`);
+    if (c.note)
+        out(io, `  note: ${c.note}`);
+    out(io, `effective for ${mode}${strategyId !== '-' ? ` · strategy ${strategyId}` : ''}${accountId !== '-' ? ` · account ${accountId}` : ''}${e.applies ? '' : ' · paper ignores the limits (add a "paper" scope to make forward tests obey them)'}:`);
+    for (const l of limitsLines(e, { all: opts.all === true }))
+        out(io, `  ${l}`);
+    const scoped = [...(c.doc.modes.real ? ['real'] : []), ...(c.doc.modes.paper ? ['paper'] : []), ...Object.keys(c.doc.strategies).map((id) => `strategy:${id}`), ...Object.keys(c.doc.accounts).map((id) => `account:${id}`)];
+    if (scoped.length)
+        out(io, `  tighter scopes set: ${scoped.join(', ')} (the stricter number always wins)`);
+    for (const a of armed)
+        out(io, `  armed ${a.id} (account ${a.accountId}): ${limitsSummary(a.limits)}`);
+    out(io, `  today: ${risk.buys} buys · ${risk.buySol} SOL · realized ${risk.dayPnlSol} SOL${risk.breaker ? ' · DRAWDOWN BREAKER TRIPPED (dexterm autotrade limits breaker reset)' : ''}${risk.pausedUntil && risk.pausedUntil > now() ? ` · loss-streak pause until ${new Date(risk.pausedUntil).toISOString().slice(11, 16)} UTC` : ''}`);
+    return 0;
+}
+/**
+ * Print the planned diff (planLimitsSave: measured from dexterm's last journaled save, so a hand edit's raises are
+ * shown too) and, when anything is raised, take the typed phrase. Returns the raises confirmed (the exact list
+ * saveLimits checks; empty when nothing raises), or null when not confirmed.
+ */
+export async function confirmPlan(io, deps, plan, unjournaled = null, what = 'limits') {
+    for (const c of plan.changes)
+        out(io, `  ${changeLine(c)}`);
+    if (!plan.raised.length)
+        return [];
+    if (unjournaled && raises(unjournaled).length)
+        out(io, `limits.json was changed outside dexterm and that edit RAISES ${raises(unjournaled).map((c) => `${c.scope}.${c.key}`).join(', ')}: it is part of this save (dexterm autotrade limits diff shows it alone)`);
+    out(io, `${plan.raised.length} limit(s) RAISED (laxer). Raising applies from the next real run; a running one keeps the stricter number.`);
+    return (await confirmTyped(io, deps, 'RAISE', what)) ? plan.raised : null;
+}
+async function setCmd(argv, io, home, deps, now) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    if (!pos.length) {
+        err(io, 'set name=value … (dexterm autotrade limits explain lists the names)');
+        return 2;
+    }
+    const c = current(home);
+    if (!c.ok) {
+        err(io, `${c.note}; fix or remove the file first`);
+        return 1;
+    }
+    const next = structuredClone(c.doc);
+    delete next.migratedFrom;
+    const scope = typeof opts.scope === 'string' ? opts.scope : 'global';
+    const ref = scopeRef(next, scope, true);
+    if ('error' in ref) {
+        err(io, ref.error);
+        return 2;
+    }
+    for (const a of pos) {
+        const p = parseLimitAssignment(a);
+        if ('error' in p) {
+            err(io, p.error);
+            return 2;
+        }
+        if (p.value === null && !ref.isGlobal) {
+            delete ref.set[p.key];
+            continue;
+        }
+        ref.set[p.key] = p.value;
+    }
+    const issues = validateLimits(next);
+    if (issues.length) {
+        for (const i of issues)
+            err(io, `${i.path}: ${i.msg}`);
+        return 2;
+    }
+    const l = loadLimits(home);
+    const plan = planLimitsSave(home, next);
+    if (!plan.changes.length && l.ok) {
+        out(io, 'unchanged');
+        return 0;
+    }
+    out(io, `limits ${scope}:`);
+    const confirmed = await confirmPlan(io, deps, plan, l.ok ? l.unjournaled : null);
+    if (!confirmed)
+        return 1;
+    const r = saveLimits(home, next, { confirmed, baseline: plan.baseline, now: now() });
+    if (!r.ok) {
+        err(io, r.why);
+        return 1;
+    }
+    if (opts.json) {
+        out(io, JSON.stringify({ saved: true, hash: r.hash, changes: r.changes }, null, 2));
+        return 0;
+    }
+    out(io, `saved (journaled, ${r.hash}) · lowered limits apply at once, even to a running real run`);
+    return 0;
+}
+function diffCmd(argv, io, home) {
+    const { opts } = parseArgs(argv, ['json']);
+    const l = loadLimits(home);
+    let before;
+    let after;
+    if (typeof opts.file === 'string') {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(opts.file, 'utf8'));
+        }
+        catch (e) {
+            err(io, `cannot read ${opts.file}: ${e.message.slice(0, 80)}`);
+            return 2;
+        }
+        const issues = validateLimits(raw);
+        if (issues.length) {
+            for (const i of issues)
+                err(io, `${i.path}: ${i.msg}`);
+            return 2;
+        }
+        before = l.ok ? l.doc : null;
+        after = raw;
+    }
+    else {
+        if (!l.ok) {
+            err(io, l.why);
+            return 1;
+        }
+        if (!l.unjournaled) {
+            out(io, 'limits.json matches dexterm\'s last save');
+            return 0;
+        }
+        if (opts.json) {
+            out(io, JSON.stringify({ unjournaled: l.unjournaled }, null, 2));
+            return 0;
+        }
+        out(io, 'limits.json vs dexterm\'s last journaled save:');
+        for (const c of l.unjournaled)
+            out(io, `  ${changeLine(c)}`);
+        if (raises(l.unjournaled).length)
+            out(io, 'it RAISES limits: a real run refuses it until you accept it (dexterm autotrade limits accept)');
+        return 0;
+    }
+    const changes = diffLimits(before, after);
+    if (opts.json) {
+        out(io, JSON.stringify({ changes }, null, 2));
+        return 0;
+    }
+    if (!changes.length) {
+        out(io, 'no change');
+        return 0;
+    }
+    for (const c of changes)
+        out(io, `  ${changeLine(c)}`);
+    return 0;
+}
+async function resetCmd(argv, io, home, deps, now) {
+    const { opts } = parseArgs(argv);
+    const c = current(home);
+    if (!c.ok) {
+        err(io, c.note ?? 'limits unreadable');
+        return 1;
+    }
+    const next = structuredClone(c.doc);
+    delete next.migratedFrom;
+    const scope = typeof opts.scope === 'string' ? opts.scope : 'global';
+    const ref = scopeRef(next, scope, false);
+    if ('error' in ref) {
+        err(io, ref.error);
+        return 2;
+    }
+    const key = typeof opts.key === 'string' ? parseLimitAssignment(`${opts.key}=0`) : null;
+    if (key && 'error' in key) {
+        err(io, key.error);
+        return 2;
+    }
+    if (!ref.set) {
+        out(io, `${scope} has nothing set`);
+        return 0;
+    }
+    if (key)
+        delete ref.set[key.key];
+    else if (ref.isGlobal)
+        next.global = {};
+    else if (scope === 'real' || scope === 'paper')
+        delete next.modes[scope];
+    else {
+        const [kind, id] = scope.split(':');
+        delete next[kind === 'strategy' ? 'strategies' : 'accounts'][id];
+    }
+    const l = loadLimits(home);
+    const plan = planLimitsSave(home, next);
+    if (!plan.changes.length) {
+        out(io, 'unchanged');
+        return 0;
+    }
+    out(io, `reset ${scope}${key ? `.${key.key}` : ''} (global numbers fall back to the placeholder defaults):`);
+    const confirmed = await confirmPlan(io, deps, plan, l.ok ? l.unjournaled : null);
+    if (!confirmed)
+        return 1;
+    const r = saveLimits(home, next, { confirmed, baseline: plan.baseline, action: 'limits-reset', now: now() });
+    if (!r.ok) {
+        err(io, r.why);
+        return 1;
+    }
+    out(io, `saved (journaled, ${r.hash})`);
+    return 0;
+}
+async function acceptCmd(io, home, deps, now) {
+    const l = loadLimits(home);
+    if (!l.ok) {
+        err(io, l.why);
+        return 1;
+    }
+    if (!l.unjournaled) {
+        out(io, 'limits.json already matches dexterm\'s last save');
+        return 0;
+    }
+    out(io, 'accept limits.json as it is now:');
+    const plan = planLimitsSave(home, l.doc);
+    const confirmed = await confirmPlan(io, deps, plan);
+    if (!confirmed)
+        return 1;
+    // task-1654 r4 (verify F4): belt and braces. The plan and the integrity check share one baseline, so they agree;
+    // should they ever not, an outside edit that raises anything still needs the typed phrase here.
+    const outside = raises(l.unjournaled).map((c) => `${c.scope}.${c.key}`);
+    if (outside.some((k) => !confirmed.includes(k))) {
+        err(io, `the edit raises ${outside.join(', ')} but the planned save does not show it: nothing accepted (dexterm autotrade limits diff)`);
+        return 1;
+    }
+    const r = saveLimits(home, l.doc, { confirmed, baseline: plan.baseline, action: 'limits-accept', now: now() });
+    if (!r.ok) {
+        err(io, r.why);
+        return 1;
+    }
+    out(io, `accepted (journaled, ${r.hash})`);
+    return 0;
+}
+function explainCmd(argv, io) {
+    const want = argv[0] ? parseLimitAssignment(`${argv[0]}=0`) : null;
+    if (want && 'error' in want) {
+        err(io, want.error);
+        return 2;
+    }
+    for (const f of LIMIT_FIELDS) {
+        if (want && f.key !== want.key)
+            continue;
+        const d = DEFAULT_LIMITS[f.key];
+        out(io, `${f.key} (${f.group}, ${f.unit}, ${f.dir === 'max' ? 'a cap: smaller is stricter' : 'a floor: larger is stricter'}; placeholder ${d === undefined ? 'off' : d})`);
+        out(io, `  ${f.help}`);
+    }
+    if (!want)
+        out(io, 'scopes: global (replaces the placeholder) · real / paper (a mode) · strategy:<id> · account:<id>; every scope but global can only tighten');
+    return 0;
+}
+// ───────────────────────────── the first-run wizard (arming) ─────────────────────────────
+/** The numbers the wizard asks for, in order. Everything else keeps its placeholder (shown) or stays off. */
+export const WIZARD_KEYS = ['perTradeSol', 'dailySol', 'buysPerDay', 'maxOpenPositions', 'dailyLossSol', 'executorSilenceMin'];
+/**
+ * No limits saved yet: ask for YOUR numbers on the real terminal (Enter keeps the placeholder shown in brackets).
+ * Returns the `global` scope to save once the arming phrase is typed, or null (cancelled / not a terminal).
+ */
+export async function limitsWizard(io, deps) {
+    if (!isTty(io, deps))
+        return null;
+    out(io, 'FIRST REAL RUN: set your own limits (they live outside the model; only you change them, on this terminal).');
+    out(io, 'The numbers in brackets are placeholders, not advice. Enter keeps one; "off" turns a limit off.');
+    const g = {};
+    for (const k of WIZARD_KEYS) {
+        const f = limitField(k);
+        let done = false;
+        for (let tries = 0; tries < 3 && !done; tries++) {
+            const ans = await typedLine(io, deps, `  ${k}: ${f.help}\n    ${f.unit} [${DEFAULT_LIMITS[k] ?? 'off'}]: `);
+            if (ans === null)
+                return null;
+            const t = ans.trim();
+            if (!t) {
+                g[k] = DEFAULT_LIMITS[k] ?? null;
+                done = true;
+                continue;
+            }
+            const p = parseLimitAssignment(`${k}=${t}`);
+            if ('error' in p) {
+                err(io, p.error);
+                continue;
+            }
+            const issues = validateLimits({ ...emptyLimits(), global: { ...g, [k]: p.value } });
+            const mine = issues.filter((i) => i.path === `/global/${k}`);
+            if (mine.length) {
+                err(io, mine.map((i) => i.msg).join('; '));
+                continue;
+            }
+            g[k] = p.value;
+            done = true;
+        }
+        if (!done) {
+            err(io, `no valid ${k}; nothing saved`);
+            return null;
+        }
+    }
+    for (const k of LIMIT_KEYS)
+        if (!(k in g) && DEFAULT_LIMITS[k] !== undefined)
+            g[k] = DEFAULT_LIMITS[k];
+    return g;
+}

package/dist/packages/cli/src/autotrade-cmd/receipt.js

@@ -0,0 +1,63 @@
+// `dexterm autotrade receipt …` (task-1645, 0.2.0 card A): what your executor did with a LIVE TRADE FIRE signal, as
+// DATA only. A receipt never makes dexterm do anything: it moves a real-mode position from `unconfirmed` to
+// executed / rejected / failed and measures the drift between the signal and the fill (ledger, Q screen, audit).
+// Your executor can also append `dexterm-trade-receipt/1` lines to autotrade/real/receipts.jsonl itself.
+import { dextermHome } from '../../../custom/src/index.js';
+import { Outbox, RECEIPT_SCHEMA, RECEIPT_STATUSES, appendReceipt, driftReport, readReceipts, receiptMismatch } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+export const RECEIPT_USAGE = 'dexterm autotrade receipt <nonce|signal-id> executed|rejected|failed [--price USD] [--size-sol N] [--tokens N] [--tx SIGNATURE] [--reason TEXT] [--executor NAME] | receipt list [--json]';
+export function receiptCmd(argv, io, o = {}) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const home = dextermHome(io.env);
+    const now = o.now ?? Date.now;
+    const ob = Outbox.open(home, { channels: [], noLock: true });
+    if (pos[0] === 'list' || !pos.length) {
+        const d = driftReport(ob.signals(), readReceipts(home).receipts, now());
+        if (opts.json) {
+            io.stdout.write(`${JSON.stringify(d, null, 2)}\n`);
+            return 0;
+        }
+        if (!d.rows.length) {
+            io.stdout.write('no trade-fire signals yet\n');
+            return 0;
+        }
+        io.stdout.write(`signals vs receipts · executed ${d.counts.executed} · rejected ${d.counts.rejected} · failed ${d.counts.failed} · unconfirmed ${d.unconfirmed}${d.orphanReceipts ? ` · ${d.orphanReceipts} orphan receipt(s) ignored` : ''}\n`);
+        for (const r of d.rows.slice(-30))
+            io.stdout.write(`  #${r.nonce} ${r.side.toUpperCase()} ${r.symbol} ${r.signalSol} SOL · ${r.state}${r.filledSol !== null ? ` · filled ${r.filledSol} SOL (${r.sizeDriftPct}%)` : ''}${r.priceDriftPct !== null ? ` · price ${r.priceDriftPct}%` : ''}${r.conflict ? ' · CONFLICTING receipts' : ''}\n`);
+        return 0;
+    }
+    const [ref, status] = pos;
+    if (!RECEIPT_STATUSES.includes(status)) {
+        io.stderr.write(`usage: ${RECEIPT_USAGE}\n`);
+        return 2;
+    }
+    const sig = /^\d+$/.test(ref) ? ob.get(Number(ref)) : ob.findById(ref);
+    const num = (k) => { if (opts[k] === undefined)
+        return null; const v = Number(opts[k]); return Number.isFinite(v) && v > 0 ? v : 'bad'; };
+    const price = num('price'), sizeSol = num('size-sol'), tokens = num('tokens');
+    if (price === 'bad' || sizeSol === 'bad' || tokens === 'bad') {
+        io.stderr.write('dexterm autotrade receipt: --price, --size-sol and --tokens are positive numbers\n');
+        return 2;
+    }
+    if (!sig) {
+        io.stderr.write(`dexterm autotrade receipt: no signal ${JSON.stringify(ref)} in the outbox\n`);
+        return 1;
+    }
+    const tx = typeof opts.tx === 'string' ? opts.tx : null;
+    const fill = price !== null || sizeSol !== null || tokens !== null || tx ? { priceUsd: price, sizeSol, tokens, txSig: tx } : null;
+    const r = { schema: RECEIPT_SCHEMA, signalId: sig.id, nonce: sig.nonce, accountId: sig.accountId, status: status, at: now(), fill, reason: typeof opts.reason === 'string' ? opts.reason : null, executor: typeof opts.executor === 'string' ? opts.executor : null };
+    const why = receiptMismatch(r, sig);
+    if (why) {
+        io.stderr.write(`dexterm autotrade receipt: ${why}\n`);
+        return 1;
+    }
+    try {
+        appendReceipt(home, r);
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade receipt: ${e.message}\n`);
+        return 2;
+    }
+    io.stdout.write(`receipt recorded · #${sig.nonce} ${status} (data only: dexterm places nothing)\n`);
+    return 0;
+}

package/dist/packages/cli/src/autotrade-cmd/report.js

@@ -0,0 +1,79 @@
+// `dexterm autotrade report …` (task-1654, 0.2.0 card E): the daily / weekly digest per strategy and mode.
+//
+//   report [--period day|week] [--strategy ID] [--json]   print it
+//   report --telegram                                      send it to your paired chat through your own bot
+//   report --schedule daily|weekly|off                     a run with the bot on sends it by itself (default off)
+//
+// Read-only over the run ledgers, the outbox and the receipts. The numbers are what they are: the digest always
+// carries the win rate's interval and a sample-size note, never a gain claim.
+import { dextermHome } from '../../../custom/src/index.js';
+import { buildDigest, digestLines, effectiveLimits, executorHealth, loadDigestState, loadLimits, readReceipts, saveDigestState, simExecutor, loadPreset } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+import { startTelegramHost } from "./telegram-host.js";
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, s) => { io.stderr.write(`dexterm autotrade report: ${s}\n`); };
+export function digestFor(home, o) {
+    const l = loadLimits(home);
+    const e = effectiveLimits(l.ok ? l.doc : null, { strategyId: '-', accountId: '-', mode: 'real' });
+    const ex = l.ok ? executorHealth(home, { now: o.now, windowMin: e.values.executorSilenceMin ?? null, receipts: readReceipts(home).receipts }) : null;
+    return buildDigest(home, { ...o, executor: ex && (ex.lastSeenAt || l.ok) ? ex : null });
+}
+/** Send lines through the user's own bot (one-shot: start, broadcast, stop). */
+export async function sendDigest(home, lines, o) {
+    const t = await startTelegramHost({ home, exec: simExecutor(loadPreset('scalp').execution), say: o.say, ...o.telegram });
+    if (!t.ok)
+        return { ok: false, why: t.why };
+    try {
+        const before = t.host.service.audit.events.length;
+        await t.host.service.hub.broadcast({ kind: 'text', badge: o.real ? 'LIVE' : 'PAPER', lines }, 'report');
+        if (t.host.service.audit.events.slice(before).some((e) => e.kind === 'out_failed'))
+            return { ok: false, why: 'telegram send failed' };
+        return { ok: true };
+    }
+    finally {
+        await t.host.stop();
+    }
+}
+export async function reportCmd(argv, io, deps = {}) {
+    const home = dextermHome(io.env);
+    const now = deps.now ?? Date.now;
+    const { pos, opts } = parseArgs(argv, ['json', 'telegram']);
+    if (pos.length) {
+        err(io, `unexpected ${pos.join(' ')}`);
+        return 2;
+    }
+    if (opts.schedule !== undefined) {
+        const v = String(opts.schedule);
+        if (!['daily', 'weekly', 'off'].includes(v)) {
+            err(io, '--schedule daily|weekly|off');
+            return 2;
+        }
+        const s = loadDigestState(home);
+        saveDigestState(home, { ...s, schedule: v });
+        out(io, v === 'off' ? 'scheduled digest off' : `scheduled digest: ${v} (sent by a run with your Telegram bot on${v === 'weekly' ? ', on Mondays' : ', after local midnight'})`);
+        return 0;
+    }
+    const period = opts.period === 'week' ? 'week' : opts.period === undefined || opts.period === 'day' ? 'day' : null;
+    if (!period) {
+        err(io, '--period day|week');
+        return 2;
+    }
+    const strategyId = typeof opts.strategy === 'string' ? opts.strategy : undefined;
+    const d = digestFor(home, { period, now: now(), strategyId });
+    if (opts.json) {
+        out(io, JSON.stringify(d, null, 2));
+        return 0;
+    }
+    const lines = digestLines(d);
+    for (const l of lines)
+        out(io, l);
+    if (opts.telegram) {
+        const r = await sendDigest(home, lines, { say: (s) => io.stderr.write(`${s}\n`), real: d.strategies.some((x) => x.mode === 'real'), telegram: deps.telegram });
+        if (!r.ok) {
+            err(io, `not sent: ${r.why}`);
+            return 1;
+        }
+        out(io, 'sent to your paired Telegram chat');
+    }
+    return 0;
+}

package/dist/packages/cli/src/autotrade-cmd/requests.js

@@ -0,0 +1,79 @@
+// `dexterm autotrade requests list|run|dismiss` (task-1530): the user's side of the MCP `backtest_request` tool. An
+// agent can only FILE a request ($DEXTERM_HOME/autotrade/requests/<id>.json); nothing runs until the user runs it here.
+// `run` is the ordinary `dexterm autotrade backtest <id> --days N` on the recorded history (paper, no network, no
+// model), and its one-line result is written back so the agent reads it with `backtest_requests`.
+import { BacktestRequests, isRequestId } from '../../../mcp/src/index.js';
+import { dextermHomeDir } from '../../../data/src/trade/ledger/index.js';
+import { backtestCmd } from "./backtest.js";
+const USAGE = 'dexterm autotrade requests [list [--all] [--json] | run <br_id> | dismiss <br_id>]';
+const when = (t) => new Date(t).toISOString().slice(0, 16).replace('T', ' ');
+function line(r) {
+    const head = `${r.requestId}  ${r.status.padEnd(9)} ${when(r.createdAt)}  ${r.id}${r.version ? `@${r.version}` : ''} · ${r.days}d${r.everyCandidate ? ' · every candidate' : ''} · by ${r.actor}`;
+    return `${head}\n    why: ${r.why}${r.result ? `\n    result: ${r.result}` : ''}`;
+}
+export async function requestsCmd(argv, io) {
+    const files = new BacktestRequests(dextermHomeDir(io.env));
+    const sub = argv[0] ?? 'list';
+    if (sub === 'list') {
+        const all = argv.includes('--all');
+        const rows = files.list(all ? {} : { status: 'pending' });
+        if (argv.includes('--json')) {
+            io.stdout.write(`${JSON.stringify({ requests: rows })}\n`);
+            return 0;
+        }
+        if (!rows.length) {
+            io.stdout.write(all ? 'no backtest requests\n' : 'no pending backtest requests (--all shows the resolved ones)\n');
+            return 0;
+        }
+        for (const r of rows)
+            io.stdout.write(`${line(r)}\n`);
+        io.stdout.write('\nAn agent filed these; nothing ran. `dexterm autotrade requests run <id>` runs one (paper, recorded data); `dismiss <id>` drops it.\n');
+        return 0;
+    }
+    if (sub !== 'run' && sub !== 'dismiss') {
+        io.stderr.write(`dexterm autotrade requests: unknown action ${JSON.stringify(sub)}\n  ${USAGE}\n`);
+        return 2;
+    }
+    const id = argv[1];
+    if (!isRequestId(id)) {
+        io.stderr.write(`dexterm autotrade requests ${sub}: pass a request id (br_…, from \`dexterm autotrade requests\`)\n`);
+        return 2;
+    }
+    const r = files.get(id);
+    if (!r) {
+        io.stderr.write(`dexterm autotrade requests: no request ${id}\n`);
+        return 2;
+    }
+    if (r.status !== 'pending') {
+        io.stderr.write(`dexterm autotrade requests: ${id} is already ${r.status}\n`);
+        return 2;
+    }
+    if (sub === 'dismiss') {
+        files.resolve(id, 'dismissed', 'dismissed by the user');
+        io.stdout.write(`${id} dismissed\n`);
+        return 0;
+    }
+    // run: the ordinary backtest, its JSON captured for the one-line result, the human report shown after
+    let out = '';
+    let err = '';
+    const args = [r.id, '--days', String(r.days), ...(r.everyCandidate ? ['--every-candidate'] : []), '--json'];
+    const rc = await backtestCmd(args, { ...io, stdout: { write: (s) => { out += s; return true; } }, stderr: { write: (s) => { err += s; return true; } } });
+    if (rc !== 0) {
+        const why = err.trim().split('\n')[0] || `the backtest exited ${rc}`;
+        files.resolve(id, 'failed', why);
+        io.stderr.write(`${id} failed: ${why}\n`);
+        return rc;
+    }
+    let result;
+    try {
+        const rep = JSON.parse(out);
+        const wr = rep.winRate ? `${rep.winRate.value}% (95% ${rep.winRate.lo}–${rep.winRate.hi}%)` : '—';
+        result = `paper backtest ${r.days}d: ${rep.trades ?? 0} trades · win ${wr} · net $${(rep.netUsd ?? 0).toFixed(2)} (${rep.netPct ?? 0}%) · max drawdown ${rep.maxDrawdownPct ?? 0}%`;
+    }
+    catch {
+        result = 'the backtest ran but its report was not readable JSON';
+    }
+    files.resolve(id, 'done', result);
+    io.stdout.write(`${id} done: ${result}\n  (the agent reads this with backtest_requests; the full report: \`dexterm autotrade backtest ${r.id} --days ${r.days}\`)\n`);
+    return 0;
+}