dexterm-cli 0.1.6 → 0.1.7

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

@@ -0,0 +1,198 @@
+// `dexterm autotrade list|validate|new|import|remove|journal` (task-1503 AT-1): the strategy store from the CLI.
+// Every write goes through @dexterm/autotrade StrategyStore (validated first, atomic, journaled with actor
+// "user"); nothing here signs, arms or trades.
+import { existsSync, readFileSync } from 'node:fs';
+import { fmtIssue, StrategyStore, validateStrategy } from '../../../autotrade/src/index.js';
+export function parseArgs(argv, booleans = []) {
+    const pos = [];
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) {
+            pos.push(a);
+            continue;
+        }
+        const eq = a.indexOf('=');
+        if (eq > 0) {
+            opts[a.slice(2, eq)] = a.slice(eq + 1);
+            continue;
+        }
+        const k = a.slice(2);
+        const v = argv[i + 1];
+        if (!booleans.includes(k) && v !== undefined && !v.startsWith('--')) {
+            opts[k] = v;
+            i++;
+        }
+        else
+            opts[k] = true;
+    }
+    return { pos, opts };
+}
+export const storeFor = (io) => new StrategyStore({ env: io.env });
+const looksLikeFile = (a) => a.endsWith('.json') || a.includes('/') || a.includes('\\');
+/** Resolve `<id|file>`: an existing path (or anything that looks like one) is a file; otherwise the store, then the presets. */
+export function resolveStrategyArg(arg, io) {
+    if (!arg)
+        return null;
+    if (looksLikeFile(arg) || existsSync(arg)) {
+        if (!existsSync(arg))
+            return { ok: false, errors: [{ path: '', msg: `no such file ${arg}` }], warnings: [], source: 'file' };
+        let doc;
+        try {
+            doc = JSON.parse(readFileSync(arg, 'utf8'));
+        }
+        catch (e) {
+            return { ok: false, errors: [{ path: '', msg: `not JSON: ${e.message}` }], warnings: [], source: 'file' };
+        }
+        return { ...validateStrategy(doc), source: 'file' };
+    }
+    try {
+        const g = storeFor(io).get(arg);
+        return g ? { ...g, source: g.source } : { ok: false, errors: [{ path: '', msg: `no strategy or preset named ${arg} (dexterm autotrade list)` }], warnings: [], source: 'store' };
+    }
+    catch (e) {
+        return { ok: false, errors: [{ path: '', msg: e.message }], warnings: [], source: 'store' };
+    }
+}
+const printIssues = (io, kind, xs, to = 'stdout') => { for (const x of xs)
+    io[to].write(`${kind} ${fmtIssue(x)}\n`); };
+export function listCmd(argv, io) {
+    const { opts } = parseArgs(argv, ['json']);
+    const store = storeFor(io);
+    const rows = store.list();
+    if (opts.json) {
+        io.stdout.write(JSON.stringify({ dir: store.dir, strategies: rows }, null, 2) + '\n');
+        return 0;
+    }
+    io.stdout.write(`STRATEGIES · PAPER · ${store.dir}\n`);
+    const w = Math.max(4, ...rows.map((r) => r.id.length));
+    for (const r of rows) {
+        const bt = r.lastBacktest ? `last backtest ${r.lastBacktest.trades} trades ${r.lastBacktest.netUsd >= 0 ? '+' : '-'}$${Math.abs(r.lastBacktest.netUsd).toFixed(2)} (${r.lastBacktest.netPct}%), dd ${r.lastBacktest.maxDrawdownPct}%` : 'no backtest yet';
+        const head = `  ${r.id.padEnd(w)}  ${(r.source + (r.shadowsPreset ? '*' : '')).padEnd(7)}`;
+        if (!r.ok) {
+            io.stdout.write(`${head}  INVALID: ${(r.errors ?? []).slice(0, 2).map(fmtIssue).join('; ')}\n`);
+            continue;
+        }
+        io.stdout.write(`${head}  v${r.version.padEnd(7)} ${r.hash}  ${r.mode.padEnd(5)}  profiles ${r.profiles.join(',')}  · ${bt}${r.highRisk ? '  · ⚠ HIGH RISK' : ''}\n`);
+    }
+    if (rows.some((r) => r.shadowsPreset))
+        io.stdout.write('  * your file shadows the shipped preset of the same id\n');
+    return 0;
+}
+export function validateCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const r = resolveStrategyArg(pos[0] ?? (typeof opts.strategy === 'string' ? opts.strategy : undefined), io);
+    if (!r) {
+        io.stderr.write('usage: dexterm autotrade validate <id|file> [--json]\n');
+        return 2;
+    }
+    if (opts.json) {
+        io.stdout.write(JSON.stringify(r.ok ? { ok: true, id: r.strategy.id, version: r.strategy.version, hash: r.strategy.hash, mode: r.strategy.mode, warnings: r.warnings } : { ok: false, errors: r.errors, warnings: r.warnings }, null, 2) + '\n');
+        return r.ok ? 0 : 2;
+    }
+    printIssues(io, 'warning', r.warnings);
+    if (!r.ok) {
+        printIssues(io, 'error', r.errors);
+        return 2;
+    }
+    const s = r.strategy;
+    io.stdout.write(`ok ${s.id} v${s.version} hash ${s.hash} mode ${s.mode}${s.mode === 'live' ? ' (does not run: dexterm runs strategies on paper only)' : ''} profiles ${Object.keys(s.exits.profiles).join(',')} (${r.source})\n`);
+    return 0;
+}
+export function newCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv);
+    const id = pos[0];
+    const from = typeof opts.from === 'string' ? opts.from : undefined;
+    if (!id || !from) {
+        io.stderr.write('usage: dexterm autotrade new <new-id> --from <preset|id> [--name TEXT]\n');
+        return 2;
+    }
+    let r;
+    try {
+        r = storeFor(io).createFrom(from, id, { actor: 'user', name: typeof opts.name === 'string' ? opts.name : undefined });
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade: ${e.message}\n`);
+        return 2;
+    }
+    if (!r.ok) {
+        printIssues(io, 'error', r.errors, 'stderr');
+        return 2;
+    }
+    printIssues(io, 'warning', r.warnings);
+    io.stdout.write(`created ${id} v${r.strategy.version} (${r.strategy.hash}) from ${from} → ${storeFor(io).pathOf(id)}\n  edit the file, then: dexterm autotrade validate ${id} · dexterm autotrade backtest ${id}\n`);
+    return 0;
+}
+export function importCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['replace']);
+    const file = pos[0];
+    if (!file || !existsSync(file)) {
+        io.stderr.write('usage: dexterm autotrade import <file> [--replace]\n');
+        return 2;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        io.stderr.write(`not JSON: ${e.message}\n`);
+        return 2;
+    }
+    // Spec §2c: an imported strategy is always paper, whatever the file says.
+    const forced = doc && typeof doc === 'object' && doc.mode !== 'paper';
+    if (forced)
+        doc = { ...doc, mode: 'paper' };
+    const store = storeFor(io);
+    const id = typeof doc.id === 'string' ? doc.id : '';
+    let r;
+    try {
+        r = opts.replace && id && store.has(id) ? store.update(id, doc, { actor: 'import', why: `import ${file}` }) : store.create(doc, { actor: 'import', why: `import ${file}` });
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade: ${e.message}\n`);
+        return 2;
+    }
+    if (!r.ok) {
+        printIssues(io, 'error', r.errors, 'stderr');
+        return 2;
+    }
+    printIssues(io, 'warning', r.warnings);
+    io.stdout.write(`imported ${r.strategy.id} v${r.strategy.version} (${r.strategy.hash})${forced ? ' · mode forced to paper' : ''}\n`);
+    return 0;
+}
+export function removeCmd(argv, io) {
+    const { pos } = parseArgs(argv);
+    if (!pos[0]) {
+        io.stderr.write('usage: dexterm autotrade remove <id>\n');
+        return 2;
+    }
+    let r;
+    try {
+        r = storeFor(io).remove(pos[0], { actor: 'user' });
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade: ${e.message}\n`);
+        return 2;
+    }
+    if (!r.ok) {
+        printIssues(io, 'error', r.errors, 'stderr');
+        return 2;
+    }
+    io.stdout.write(`removed ${pos[0]} → ${r.movedTo}\n`);
+    return 0;
+}
+export function journalCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const j = storeFor(io).journal(pos[0]);
+    if (opts.json) {
+        io.stdout.write(JSON.stringify(j, null, 2) + '\n');
+        return 0;
+    }
+    if (!j.length) {
+        io.stdout.write('no strategy changes journaled yet\n');
+        return 0;
+    }
+    for (const x of j)
+        io.stdout.write(`${new Date(x.t).toISOString()}  ${x.action.padEnd(6)} ${x.id.padEnd(20)} by ${x.actor.padEnd(8)} ${x.beforeHash ?? '—'} → ${x.afterHash ?? '—'}${x.version ? ` v${x.version}` : ''}  ${x.ops.length} op(s)${x.why ? ` · ${x.why}` : ''}\n`);
+    return 0;
+}

package/dist/packages/cli/src/autotrade-cmd/strategy-control.js

@@ -0,0 +1,174 @@
+// `dexterm autotrade status [--all]`, `start <strategy>`, `pause | resume [--strategy ID]`, and the per-strategy
+// `stop | flatten --strategy ID` (task-1529, parallel strategies). PAPER ONLY.
+//
+// Without --strategy, pause and resume act on the whole runner (control.json, like the Q screen's `p`), whether it
+// runs one strategy or several. With --strategy they act on one strategy of `dexterm autotrade run --all` through its
+// own control file (autotrade/fleet/<id>.control.json): another strategy never sees it. `start` starts a strategy of
+// autotrade.json that is not running (paper, with its own config; nothing else can be changed from here).
+// Nothing here touches a wallet, a key or the signer.
+import { dextermHome } from '../../../custom/src/index.js';
+import { accountTable, activeRunner, compareRows, compareTable, fleetTotals, readFleetStatus, requestControl, requestMemberControl, } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+export const STATUS_USAGE = 'dexterm autotrade status [--all] [--json]';
+export const START_USAGE = 'dexterm autotrade start <strategy> [--wait SEC] [--json]';
+export const PAUSE_USAGE = 'dexterm autotrade pause [--strategy ID] [--json]';
+export const RESUME_USAGE = 'dexterm autotrade resume [--strategy ID] [--json]';
+const tick = (ms) => new Promise((r) => setTimeout(r, ms));
+const waitSec = (v, dflt = 10) => { const n = typeof v === 'string' ? Number(v) : NaN; return Number.isFinite(n) && n >= 0 ? Math.min(n, 120) : dflt; };
+function memberNow(home, id) {
+    const st = readFleetStatus(home);
+    return st.ok ? st.status.members.find((m) => m.id === id) ?? null : null;
+}
+/** True once the strategy's state shows the request (or the fleet is gone). */
+function acknowledged(m, action, runId) {
+    if (!m)
+        return true;
+    switch (action) {
+        case 'start': return m.runId !== null && m.runId !== runId && m.state !== 'idle';
+        case 'stop': return m.runId !== runId || m.state === 'stopped' || m.state === 'halted';
+        case 'flatten': return m.runId !== runId || m.state === 'stopped' || m.haltReason === 'flatten';
+        case 'pause': return m.state === 'paused' || m.state === 'halted' || m.state === 'stopped';
+        case 'resume-entries': return m.state !== 'paused';
+    }
+}
+/** Write one strategy's request and wait up to `wait` seconds for its runner to show it. */
+export async function sendMemberControl(io, id, action, wait) {
+    const home = dextermHome(io.env);
+    const before = memberNow(home, id);
+    const w = requestMemberControl(home, id, action, 'cli');
+    if (!w.ok)
+        return { error: w.why };
+    const prevRun = action === 'start' ? before?.runId ?? null : w.request.runId;
+    const until = Date.now() + wait * 1000;
+    let cur = memberNow(home, id);
+    while (!acknowledged(cur, action, prevRun) && Date.now() < until) {
+        await tick(200);
+        cur = memberNow(home, id);
+    }
+    return { strategy: id, action, requested: true, already: w.already, acknowledged: acknowledged(cur, action, prevRun), runId: cur?.runId ?? null, state: cur?.state ?? null };
+}
+const WORD = { start: 'start', stop: 'stop', flatten: 'flatten', pause: 'pause', 'resume-entries': 'resume' };
+export function printMemberOutcome(io, res, json) {
+    if (json) {
+        io.stdout.write(`${JSON.stringify(res)}\n`);
+        return;
+    }
+    io.stdout.write(`${WORD[res.action]} ${res.already ? 'was already requested' : 'requested'} for strategy ${res.strategy} (the others are not touched)\n`);
+    if (!res.acknowledged)
+        io.stdout.write('the runner has not confirmed yet: it reads the request on its next tick. `dexterm autotrade status --all` shows each strategy.\n');
+    else
+        io.stdout.write(`✓ ${res.strategy}: ${res.state ?? 'gone'}${res.action === 'start' && res.runId ? ` (run ${res.runId})` : ''}\n`);
+}
+/** `dexterm autotrade stop | flatten --strategy ID` (called from stop.ts / flatten.ts). */
+export async function memberStopCmd(io, id, action, opts) {
+    const res = await sendMemberControl(io, id, action, waitSec(opts.wait));
+    if ('error' in res) {
+        io.stderr.write(`dexterm autotrade ${action}: ${res.error}\n`);
+        return 1;
+    }
+    printMemberOutcome(io, res, !!opts.json);
+    return 0;
+}
+export async function startCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const id = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
+    if (!id || pos.length > 1) {
+        io.stderr.write(`usage: ${START_USAGE}\n  (starts a strategy of autotrade.json in the running \`dexterm autotrade run --all --paper\`)\n`);
+        return 2;
+    }
+    const res = await sendMemberControl(io, id, 'start', waitSec(opts.wait));
+    if ('error' in res) {
+        io.stderr.write(`dexterm autotrade start: ${res.error}\n`);
+        return 1;
+    }
+    printMemberOutcome(io, res, !!opts.json);
+    return 0;
+}
+async function pauseResume(argv, io, action) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const name = action === 'pause' ? 'pause' : 'resume';
+    if (pos.length) {
+        io.stderr.write(`usage: ${action === 'pause' ? PAUSE_USAGE : RESUME_USAGE}\n`);
+        return 2;
+    }
+    if (typeof opts.strategy === 'string') {
+        const res = await sendMemberControl(io, opts.strategy, action, waitSec(opts.wait, 5));
+        if ('error' in res) {
+            io.stderr.write(`dexterm autotrade ${name}: ${res.error}\n`);
+            return 1;
+        }
+        printMemberOutcome(io, res, !!opts.json);
+        return 0;
+    }
+    const home = dextermHome(io.env);
+    const r = activeRunner(home);
+    if (!r) {
+        io.stdout.write(opts.json ? `${JSON.stringify({ requested: false, why: 'no autotrade runner is running' })}\n` : `no autotrade runner is running; nothing to ${name}\n`);
+        return 0;
+    }
+    const w = requestControl(home, r.runId, action, 'cli');
+    if (!w.ok) {
+        io.stderr.write(`dexterm autotrade ${name}: ${w.why}\n`);
+        return 1;
+    }
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify({ requested: true, runId: r.runId, action })}\n`);
+        return 0;
+    }
+    io.stdout.write(action === 'pause'
+        ? `pause requested for run ${r.runId}: no new entries${r.runId.includes('-fleet-') ? ' in any strategy' : ''}; open positions keep their exits (\`dexterm autotrade resume\` lifts it)\n`
+        : `resume requested for run ${r.runId}: new entries allowed again\n`);
+    return 0;
+}
+export const pauseCmd = (argv, io) => pauseResume(argv, io, 'pause');
+export const resumeCmd = (argv, io) => pauseResume(argv, io, 'resume-entries');
+export function statusCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['all', 'json']);
+    if (pos.length) {
+        io.stderr.write(`usage: ${STATUS_USAGE}\n`);
+        return 2;
+    }
+    const home = dextermHome(io.env);
+    const r = activeRunner(home);
+    const fs = readFleetStatus(home);
+    const fleetCurrent = fs.ok && r?.runId === fs.status.fleetId;
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify({
+            paper: true, runner: r,
+            ...(fs.ok && (opts.all || fleetCurrent) ? { fleet: { fleetId: fs.status.fleetId, state: r?.runId === fs.status.fleetId ? fs.status.state : 'stopped', stale: fs.stale, global: fs.status.global, totals: fleetTotals(fs.status), strategies: compareRows(fs.status), ...(fs.status.accounts ? { accounts: fs.status.accounts } : {}) } } : {}),
+        }, null, 2)}\n`);
+        return 0;
+    }
+    if (!r)
+        io.stdout.write('no autotrade runner is running\n');
+    else
+        io.stdout.write(`paper runner ${r.runId} (pid ${r.pid}) · ${r.state ?? 'starting'}${r.haltReason ? ` (${r.haltReason})` : ''} · ${r.positions} open · ${r.sessions} sessions${r.heartbeatAt ? ` · heartbeat ${Math.round((Date.now() - r.heartbeatAt) / 1000)} s ago` : ''}\n`);
+    if (!opts.all && !fleetCurrent) {
+        if (r)
+            io.stdout.write('(one strategy; `dexterm autotrade run --all --paper` runs every strategy of autotrade.json at once)\n');
+        return 0;
+    }
+    if (!fs.ok) {
+        io.stdout.write(`parallel strategies: ${fs.why}\n`);
+        return 0;
+    }
+    const st = fs.status;
+    const running = r?.runId === st.fleetId;
+    io.stdout.write(`\nPARALLEL STRATEGIES · PAPER · fleet ${st.fleetId} · ${running ? st.state : 'ended'}${fs.stale && running ? ' (heartbeat stale)' : ''} · ${st.source}\n`);
+    const g = st.global;
+    io.stdout.write(`global: ${g.liveSessions}/${g.caps.maxConcurrentSessions} sessions open · $${g.today.modelUsd.toFixed(2)}/$${g.caps.modelUsdPerDay} model spend today · ${g.today.candidateSessions}/${g.caps.candidateSessionsPerDay} candidate sessions · load ${g.load.load1m ?? '—'}${g.load.paused ? ' (sessions paused: machine busy)' : ''}${g.blocked ? ` · blocked: ${g.blocked}` : ''}\n\n`);
+    for (const l of compareTable(compareRows(st)))
+        io.stdout.write(`${l}\n`);
+    const acct = accountTable(st);
+    if (acct.length)
+        io.stdout.write(`\npaper accounts (shared simulated wallets):\n${acct.join('\n')}\n`);
+    const tot = fleetTotals(st);
+    io.stdout.write(`\ntogether: ${tot.pnlUsd >= 0 ? '+' : '-'}$${Math.abs(tot.pnlUsd).toFixed(2)}${tot.pnlPct === null ? '' : ` (${tot.pnlPct >= 0 ? '+' : ''}${tot.pnlPct}%)`} on $${tot.startUsd.toFixed(2)} · ${tot.closed} closed · ${tot.open} open · $${tot.spendUsd.toFixed(4)} model spend. Paper, simulated fills; not financial advice.\n`);
+    const missed = st.members.flatMap((m) => m.stats.missedSample.map((x) => `${m.id}: ${x.symbol} ${x.x}x`));
+    if (missed.length)
+        io.stdout.write(`missed runners (seen, not entered, later >= 2x): ${missed.slice(0, 6).join(' · ')}\n`);
+    for (const m of st.members)
+        if (m.state === 'error')
+            io.stdout.write(`${m.id}: failed: ${m.error ?? 'unknown'}\n`);
+    return 0;
+}

package/dist/packages/cli/src/autotrade-cmd/telegram-host.js

@@ -0,0 +1,101 @@
+// The Telegram side of `dexterm autotrade run --paper` (task-1527, AUTOTRADE-SPEC §8). PAPER today.
+//
+// When `dexterm telegram setup` stored a token and a chat is paired, the runner starts the user's own bot in the
+// same process: notify (the run ledger as it is written), control (/status /pause /kill …, through the same control
+// file the CLI writes) and approve-to-trade (proposals with one-tap buttons; the order then goes through the paper
+// port, which wraps the runner's paper executor and spends a single-use proof per approved order). A /use switch
+// takes effect when the run has closed out its positions: the host starts the next run with the new strategy.
+// The PnL card of a closed trade is the app's card renderer over the position's ledger fills (USD book, priced in
+// SOL with the coin's own DexScreener SOL quote at the close; no image when there is none).
+// task-1571: the bot is the user's OWN bot and the port is always the paper port. dexterm holds no key and places no
+// live order; an approval only ever releases a PAPER order.
+import { PaperPort, TelegramConnector, TelegramService, loadConnectors, secretStore, } from '../../../autotrade/src/index.js';
+/** Why a Telegram approval is refused for a strategy that is not paper (dexterm places no live order). */
+export const LIVE_APPROVALS_REFUSED = 'live-approval-port-not-installed';
+export class TelegramHost {
+    service;
+    port;
+    runId = null;
+    strategy = null;
+    state = null;
+    next = null;
+    execRef;
+    /** SOL/USD near a coin for the card, set per run (a /use switch starts a new data layer). */
+    solUsdFor;
+    constructor(o, connector, knownToken = null) {
+        this.execRef = { exec: o.exec };
+        this.solUsdFor = o.solUsdFor ?? null;
+        const exec = { name: o.exec.name, buy: (k, usd, ctx) => this.execRef.exec.buy(k, usd, ctx), sell: (k, t, r) => this.execRef.exec.sell(k, t, r) };
+        // A Telegram approval is a paper proof: every approval for a strategy that is not mode "paper" is refused here
+        // (notify and /kill keep working).
+        this.port = new PaperPort(exec, { now: o.now, entryBlock: () => (this.strategy && this.strategy.mode !== 'paper' ? LIVE_APPROVALS_REFUSED : null) });
+        this.service = new TelegramService({
+            home: o.home, connector, port: this.port, now: o.now, timers: o.timers, knownToken: () => knownToken,
+            runId: () => this.runId, state: () => this.state, strategy: () => this.strategy,
+            onSwitch: (s) => { this.next = s; o.say(`telegram: switch to ${s.id} v${s.version} confirmed; it starts once nothing is held`); },
+            alert: (line) => o.say(`! ${line}`),
+            card: (t) => (this.solUsdFor ? autotradeCardPng(t, this.solUsdFor) : Promise.resolve(null)), // the card is a paper card
+        });
+    }
+    /** Point the host at the run that is starting (a /use switch starts a new one in the same process). */
+    attach(runId, s, exec, solUsdFor) {
+        this.runId = runId;
+        this.strategy = s;
+        this.state = null;
+        this.next = null;
+        this.execRef.exec = exec;
+        if (solUsdFor)
+            this.solUsdFor = solUsdFor;
+    }
+    onLedger = (e) => this.service.onLedger(e);
+    onState = (st) => { this.state = st; this.service.onState(st); };
+    /** The strategy a confirmed /use asked for, once (null when none). */
+    takeSwitch() { const n = this.next; this.next = null; return n; }
+    async stop() { await this.service.stop(); }
+}
+/** Start the bot for a run when it is set up and paired; `quiet` = it is simply not set up (say nothing). */
+export async function startTelegramHost(o) {
+    const r = loadConnectors(o.home);
+    if (!r.ok)
+        return { ok: false, why: r.error, quiet: false };
+    const t = r.config.telegram;
+    if (!t.enabled || !t.allow.length)
+        return { ok: false, why: 'telegram is not set up (dexterm telegram setup)', quiet: !t.enabled && !r.exists };
+    let token = null;
+    let connector = o.connector;
+    if (!connector) {
+        const store = o.store ?? (t.secretStore ? secretStore(t.secretStore, o.home) : null);
+        token = store?.get() ?? null;
+        if (!token)
+            return { ok: false, why: 'the bot token is missing from the secret store (dexterm telegram setup)', quiet: false };
+        const tk = token;
+        connector = new TelegramConnector({ token: () => tk, onLog: (l) => o.say(`telegram: ${l}`) });
+    }
+    const host = new TelegramHost(o, connector, token);
+    await host.service.start();
+    return { ok: true, host };
+}
+/** The PnL card PNG of an autotrade paper trade (pnl-card.ts over the position's fills), or null. */
+export async function autotradeCardPng(t, solUsdFor) {
+    const fills = t.fills ?? [];
+    if (!fills.some((f) => f.side === 'buy'))
+        return null;
+    const solUsd = await solUsdFor(t.mint).catch(() => null);
+    if (!solUsd || !(solUsd > 0))
+        return null;
+    const card = await import("../pnl-card.js");
+    const DEC = 6;
+    const input = {
+        source: 'paper', mint: t.mint, symbol: t.symbol, name: null, decimals: DEC,
+        fills: fills.map((f) => ({ t: f.t, side: f.side, solDelta: (f.side === 'buy' ? -1 : 1) * (f.usd / solUsd), tokenDelta: BigInt(Math.round(f.tokens * 10 ** DEC)) * (f.side === 'buy' ? 1n : -1n), feeSol: null, sig: null })),
+        ledger: `dexterm autotrade paper run (USD book, SOL at $${solUsd.toFixed(2)})`, wallet: null, mark: null,
+        excluded: [], fees: 'modelled fee, slippage and price impact included',
+    };
+    try {
+        const stats = card.computeCard(input, t.closedAt);
+        return new Uint8Array(card.cardPng(stats, { aspect: 'wide' }));
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,168 @@
+// `dexterm autotrade <sub>` (task-1503 AT-1, AUTOTRADE-SPEC). PAPER ONLY: no keys, no wallet, no signer.
+//
+// A dispatcher table: each subcommand is one row that lazy-loads its own module under ./autotrade-cmd/, so
+// later cards add a row (run, service, stop, flatten, audit) without editing anyone else's lines.
+// `dexterm backtest --subject strategy …` is routed here too (the strategy subject runs on this engine).
+export const SUBCOMMANDS = {
+    list: {
+        usage: 'dexterm autotrade list [--json]',
+        summary: 'your strategies (~/.dexterm/strategies) and the shipped presets: version, hash, mode, profiles, last backtest',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.listCmd),
+    },
+    validate: {
+        usage: 'dexterm autotrade validate <id|file> [--json]',
+        summary: 'check a strategy file or a stored strategy; every problem is printed with its path',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.validateCmd),
+    },
+    new: {
+        usage: 'dexterm autotrade new <new-id> --from <preset|id> [--name TEXT]',
+        summary: 'copy a preset (or one of your strategies) into ~/.dexterm/strategies/<new-id>.json to edit',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.newCmd),
+    },
+    import: {
+        usage: 'dexterm autotrade import <file> [--replace]',
+        summary: 'validate a strategy file and store it (mode is forced to paper; --replace needs a higher version)',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.importCmd),
+    },
+    remove: {
+        usage: 'dexterm autotrade remove <id>',
+        summary: 'move one of your strategies to ~/.dexterm/strategies/.removed/ (journaled; presets cannot be removed)',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.removeCmd),
+    },
+    journal: {
+        usage: 'dexterm autotrade journal [<id>] [--json]',
+        summary: 'the append-only change journal: who changed what, with the before and after hashes',
+        load: () => import("./autotrade-cmd/strategies.js").then((m) => m.journalCmd),
+    },
+    backtest: {
+        usage: 'dexterm autotrade backtest <id|file> [--tape FILE | --db PATH [--days N | --since T] [--until T]] [--every-candidate [--unit-usd 20]] [--recall 5,10] [--json]',
+        summary: 'replay a strategy over recorded history with modelled fills (paper); the limits of the data are always printed',
+        load: () => import("./autotrade-cmd/backtest.js").then((m) => m.backtestCmd),
+    },
+    sweep: {
+        usage: 'dexterm autotrade sweep <id|file> [--tape FILE | --db PATH] [--grid JSON] [--mode grid|random] [--max N] [--seed N] [--json]',
+        summary: 'tune on the older coins, check once on the newest 30% it never saw; no gain wording without enough trades and a held-out profit',
+        load: () => import("./autotrade-cmd/backtest.js").then((m) => m.sweepCmd),
+    },
+    'yolo-replay': {
+        usage: 'dexterm autotrade yolo-replay <id|file> [--tape FILE | --db PATH [--days N | --since T] [--until T]] [--seed N] [--json]',
+        summary: 'HIGH RISK check before arming a full-port strategy: replay it at 100% of the book over recorded history (paper): rugs, the loss spread, how often it zeroed the wallet',
+        load: () => import("./autotrade-cmd/backtest.js").then((m) => m.yoloReplayCmd),
+    },
+    requests: {
+        usage: 'dexterm autotrade requests [list [--all] [--json] | run <br_id> | dismiss <br_id>]',
+        summary: 'backtests an agent asked for over MCP (backtest_request): nothing runs until you run one here (paper, recorded data)',
+        load: () => import("./autotrade-cmd/requests.js").then((m) => m.requestsCmd),
+    },
+    run: {
+        usage: 'dexterm autotrade run <id|file> --paper [--replay TAPE [--ms-per-tick 2000]] [--model M] [--max-minutes N] [--stub] [--raw] [--quiet] [--no-telegram]',
+        summary: 'the paper runner: the screener hands each candidate to your own Claude (runner.json picks the account), every size clamped; ledger in autotrade/runs/; your paired Telegram bot starts with it (dexterm telegram setup)',
+        load: () => import("./autotrade-cmd/run.js").then((m) => m.runCmd),
+    },
+    'run --all': {
+        usage: 'dexterm autotrade run --all --paper [--config FILE] [--replay TAPE] [--sol-usd N] [--stub] [--max-minutes N]',
+        summary: 'every strategy of autotrade/autotrade.json at once on one data feed: each its own bankroll, ledger, caps and budget, under global caps',
+        load: () => import("./autotrade-cmd/fleet.js").then((m) => m.fleetRunCmd),
+    },
+    status: {
+        usage: 'dexterm autotrade status [--all] [--json]',
+        summary: 'the paper runner now; --all: every strategy of a parallel run side by side (P/L, win rate, rug exposure, missed runners, spend per entry)',
+        load: () => import("./autotrade-cmd/strategy-control.js").then((m) => m.statusCmd),
+    },
+    start: {
+        usage: 'dexterm autotrade start <strategy> [--wait SEC] [--json]',
+        summary: 'start one strategy of autotrade.json inside the running `run --all` (paper, its own book and caps)',
+        load: () => import("./autotrade-cmd/strategy-control.js").then((m) => m.startCmd),
+    },
+    pause: {
+        usage: 'dexterm autotrade pause [--strategy ID] [--json]',
+        summary: 'no new entries (every strategy, or just one with --strategy); open positions keep their exits',
+        load: () => import("./autotrade-cmd/strategy-control.js").then((m) => m.pauseCmd),
+    },
+    resume: {
+        usage: 'dexterm autotrade resume [--strategy ID] [--json]',
+        summary: 'lift a pause (every strategy, or just one with --strategy); a stop is final and is never lifted',
+        load: () => import("./autotrade-cmd/strategy-control.js").then((m) => m.resumeCmd),
+    },
+    stop: {
+        usage: 'dexterm autotrade stop [--strategy ID] [--wait SEC] [--json]',
+        summary: 'soft-stop the paper runner: no new entries, sessions closed, orders dropped; mechanical exits keep running until nothing is held',
+        load: () => import("./autotrade-cmd/stop.js").then((m) => m.stopCmd),
+    },
+    flatten: {
+        usage: 'dexterm autotrade flatten [--strategy ID] [--yes] [--wait SEC] [--json]',
+        summary: 'stop, then sell every paper position at its next tick (confirm with y on a terminal, or --yes)',
+        load: () => import("./autotrade-cmd/flatten.js").then((m) => m.flattenCmd),
+    },
+    audit: {
+        usage: 'dexterm autotrade audit [<run-id>|--last] [--verify] [--json]',
+        summary: 'list the run ledgers; --verify recomputes each hash chain and names the first edited, missing or reordered event',
+        load: () => import("./autotrade-cmd/audit.js").then((m) => m.auditCmd),
+    },
+    extract: {
+        usage: 'dexterm autotrade extract --out FILE [--db PATH] [--max-mints N] [--min-peak-liq USD] [--span-hours H]',
+        summary: 'save a replay tape from your recorder history (read-only) to a file you can backtest offline',
+        load: () => import("./autotrade-cmd/backtest.js").then((m) => m.extractCmd),
+    },
+};
+export function autotradeHelp() {
+    return [
+        'dexterm autotrade: strategies, backtests and the paper runner. PAPER ONLY, not financial advice.',
+        '',
+        ...Object.values(SUBCOMMANDS).map((s) => `  ${s.usage}\n      ${s.summary}`),
+        '',
+        '  Strategies live in $DEXTERM_HOME/strategies (default ~/.dexterm/strategies), one JSON file each, with an',
+        '  append-only .journal.jsonl. Presets: scalp, swing, runner, moonbag, sample-dip-ladder, yolo (HIGH RISK) (read-only; copy one with `new`).',
+        '  `dexterm backtest --subject strategy --strategy <id|file>` runs the same backtest.',
+    ].join('\n') + '\n';
+}
+/** The value of `--subject` (or `--subject=x`) in an argv, if any. */
+function subjectOf(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--subject')
+            return argv[i + 1];
+        if (argv[i].startsWith('--subject='))
+            return argv[i].slice('--subject='.length);
+    }
+    return undefined;
+}
+/** True for `dexterm autotrade …` and `dexterm backtest --subject strategy …`. */
+export function handles(argv) {
+    return argv[0] === 'autotrade' || (argv[0] === 'backtest' && subjectOf(argv) === 'strategy');
+}
+export async function autotradeCommand(argv, io) {
+    let rest;
+    if (argv[0] === 'backtest') {
+        // `dexterm backtest --subject strategy [--strategy X] …` → `dexterm autotrade backtest [X] …`
+        rest = ['backtest'];
+        for (let i = 1; i < argv.length; i++) {
+            if (argv[i] === '--subject') {
+                i++;
+                continue;
+            }
+            if (argv[i].startsWith('--subject='))
+                continue;
+            rest.push(argv[i]);
+        }
+    }
+    else
+        rest = argv.slice(1);
+    const sub = rest[0];
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        io.stdout.write(autotradeHelp());
+        return 0;
+    }
+    // `run --all` has its own row (parallel strategies, task-1529) so its --help shows its own flags.
+    const key = sub === 'run' && rest.includes('--all') ? 'run --all' : sub;
+    const row = Object.hasOwn(SUBCOMMANDS, key) ? SUBCOMMANDS[key] : undefined;
+    if (!row) {
+        io.stderr.write(`dexterm autotrade: unknown subcommand ${JSON.stringify(sub)}\n\n${autotradeHelp()}`);
+        return 2;
+    }
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.stdout.write(`${row.usage}\n  ${row.summary}\n`);
+        return 0;
+    }
+    const fn = await row.load();
+    return fn(rest.slice(1), io);
+}