dexterm-cli 0.1.6 → 0.2.0

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

@@ -0,0 +1,76 @@
+// `dexterm autotrade stop` (task-1509 AT-7, AUTOTRADE-SPEC §6.3). PAPER ONLY.
+//
+// A soft stop of the running paper runner: no new entries, every session closed, pending orders dropped, and the
+// mechanical exits (stops, take-profits, trails, rug exits) keep running until nothing is held; then the runner
+// ends. It writes a request for that run into $DEXTERM_HOME/autotrade/control.json, which the runner re-reads on every
+// step, and waits a few seconds for the runner to confirm through its rendezvous. A stop is final for the run.
+// `dexterm wallet panic` is the harder switch: every paper desk and signer re-reads it, and only
+// `dexterm wallet resume` on a real terminal lifts it. Nothing here touches a wallet, a key or the signer.
+import { dextermHome } from '../../../custom/src/index.js';
+import { activeRunner, requestControl } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+export const STOP_USAGE = 'dexterm autotrade stop [--strategy ID] [--wait SEC] [--json]';
+const tick = (ms) => new Promise((r) => setTimeout(r, ms));
+/** True once the runner shows the request in its rendezvous (or is gone). */
+function acknowledged(r, runId, action) {
+    if (!r || r.runId !== runId)
+        return true;
+    if (r.state === 'stopped')
+        return true;
+    return action === 'flatten' ? r.haltReason === 'flatten' : r.haltReason !== null && r.state === 'halted';
+}
+/** Send stop or flatten to the active runner and wait up to waitSec for it to confirm. */
+export async function sendControl(io, action, waitSec, runner) {
+    const home = dextermHome(io.env);
+    const w = requestControl(home, runner.runId, action, 'cli');
+    if (!w.ok)
+        return { error: w.why };
+    const until = Date.now() + Math.max(0, waitSec) * 1000;
+    let cur = activeRunner(home);
+    while (!acknowledged(cur, runner.runId, action) && Date.now() < until) {
+        await tick(200);
+        cur = activeRunner(home);
+    }
+    const same = cur && cur.runId === runner.runId ? cur : null;
+    return { requested: true, runId: runner.runId, acknowledged: acknowledged(cur, runner.runId, action), already: w.already, positions: same ? same.positions : 0, sessions: same ? same.sessions : 0, ended: !same || same.state === 'stopped' };
+}
+export function waitArg(v) {
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) && n >= 0 ? Math.min(n, 120) : 10;
+}
+export async function stopCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    if (pos.length) {
+        io.stderr.write(`usage: ${STOP_USAGE}\n`);
+        return 2;
+    }
+    // task-1529: one strategy of a parallel run; the others keep running.
+    if (typeof opts.strategy === 'string')
+        return (await import("./strategy-control.js")).memberStopCmd(io, opts.strategy, 'stop', opts);
+    const home = dextermHome(io.env);
+    const r = activeRunner(home);
+    if (!r) {
+        if (opts.json)
+            io.stdout.write(`${JSON.stringify({ requested: false, runId: null, why: 'no autotrade runner is running' })}\n`);
+        else
+            io.stdout.write('no autotrade runner is running; nothing to stop. (`dexterm wallet panic` halts every paper desk and signer.)\n');
+        return 0;
+    }
+    const res = await sendControl(io, 'stop', waitArg(opts.wait), r);
+    if ('error' in res) {
+        io.stderr.write(`dexterm autotrade stop: ${res.error}\n`);
+        return 1;
+    }
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify(res)}\n`);
+        return 0;
+    }
+    io.stdout.write(`stop ${res.already ? 'was already requested' : 'requested'} for run ${r.runId} (pid ${r.pid})\n`);
+    if (!res.acknowledged)
+        io.stdout.write('the runner has not confirmed yet: it reads the request on its next tick. Watch the Q screen, or run this again.\n');
+    else if (res.ended)
+        io.stdout.write('✓ the runner stopped (nothing was held)\n');
+    else
+        io.stdout.write(`✓ halted: no new entries, sessions closed, orders dropped${res.positions ? `; ${res.positions} paper position${res.positions === 1 ? '' : 's'} keep${res.positions === 1 ? 's' : ''} its mechanical exits until closed (\`dexterm autotrade flatten\` sells now)` : ''}\n`);
+    return 0;
+}

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