dexterm-cli 0.1.5 → 0.1.7

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

@@ -0,0 +1,397 @@
+// `dexterm autotrade run --all --paper` (task-1529): every strategy of autotrade.json at the same time, on ONE data
+// feed. PAPER ONLY.
+//
+// The host around @dexterm/autotrade runFleet (fleet.ts): one process, one runner lock under the fleet's run id, one
+// live data layer (or one paced tape), one shared dossier cache, one machine-load check and the global caps of
+// autotrade.json; each strategy gets its own run id, ledger (autotrade/runs/<runId>.jsonl), simulated book (its own
+// bankroll), breaker, sessions and spend budget.
+//
+// Files it writes, every heartbeat (10 s) and on change (throttled to 1 s):
+//   autotrade/runner-status.json   the runner rendezvous, as an AGGREGATE of every strategy (book summed, positions /
+//                                  candidates / sessions tagged with their strategy), under the fleet's run id: the
+//                                  Q screen's runner view, `dexterm autotrade stop|flatten`, the monitor's dead-man and
+//                                  the MCP autotrade_status read it unchanged
+//   autotrade/fleet-status.json    each strategy's state, book, spend and stats, the global caps and their use today
+//   autotrade/runs/<id>.summary.json  each strategy's run summary and the fleet's (for `dexterm autotrade audit`)
+//
+// Paper accounts (task-1538): autotrade.json `accounts` are shared simulated wallets; a strategy with `account` trades
+// from that wallet's cash (and one strategy can run on several accounts). Printed as their own table at the end.
+//
+// Switches: the panic file, `dexterm autotrade stop | flatten` and the Q screen's `!` / `f` / `p` act on EVERY strategy
+// (the fleet's RunnerSafety); `dexterm autotrade stop | flatten | pause | resume --strategy ID` and `start ID` act on one
+// (fleet-control.ts). Nothing here arms a mandate, signs, holds a key or touches a wallet; `--live` and `mode: live`
+// are refused (task-1571: dexterm places no live order).
+import { appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { dextermHome } from '../../../custom/src/index.js';
+import { KillSwitch, createDataLayer, defaultDbPath, resolveRpcUrl } from '../../../data/src/index.js';
+import { FleetGuard, HEARTBEAT_MS, accountTable, LiveSource, RUNNER_RENDEZVOUS_SCHEMA, RUN_SUMMARY_SCHEMA, RunnerSafety, acquireRunLock, bankrollUsd, claudeSessionFactory, clearControl, clearMemberControls, clearStaleControl, compareRows, compareTable, controlPath, fileLedger, fleetStatusPath, fleetTotals, loadFleetConfig, loadRunnerConfig, loadTape, memberStrategy, newRunId, prepareAccount, releaseRunLock, renderDossierRecord, runFleet, runFiles, runnerRendezvousPath, runnerSystemPrompt, sharedDossier, stubSession, writeJsonAtomic, writeRendezvous, } from '../../../autotrade/src/index.js';
+import { parseArgs, resolveStrategyArg } from "./strategies.js";
+import { larpVet } from "./run.js";
+export const FLEET_RUN_USAGE = 'dexterm autotrade run --all --paper [--config FILE] [--replay TAPE [--ms-per-tick 2000]] [--sol-usd N] [--model M] [--max-minutes N] [--stub] [--raw] [--quiet]';
+const BOOL = ['all', 'paper', 'live', 'stub', 'quiet', 'raw'];
+const SOL_MINT = 'So11111111111111111111111111111111111111112';
+function num(v, dflt) {
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+const round2 = (v) => Math.round(v * 100) / 100;
+/** The single-runner rendezvous shape, filled with every strategy together (the existing readers need no change). */
+export function aggregateRendezvous(st, states, tails) {
+    const tot = fleetTotals(st);
+    const live = st.members.filter((m) => m.runId && m.state !== 'stopped' && m.state !== 'error' && m.state !== 'idle');
+    const runnerState = st.state === 'stopped' ? 'stopped' : st.state === 'halted' ? 'halted'
+        : live.length && live.every((m) => m.state === 'paused' || m.state === 'halted') ? 'paused' : 'running';
+    const each = (pick, m) => (states.get(m) ? pick(states.get(m)) : []);
+    const ids = st.members.map((m) => m.id);
+    return {
+        schema: RUNNER_RENDEZVOUS_SCHEMA, pid: st.pid, mode: 'paper', runId: st.fleetId, startedAt: st.startedAt, ledgerPath: st.ledgerPath,
+        state: runnerState, haltReason: st.haltReason ?? (st.global.blocked ? `fleet: ${st.global.blocked}` : st.global.load.paused ? 'fleet-load-high' : null),
+        strategy: { id: 'parallel', version: `${st.members.length} strategies`, hash: st.fleetId.slice(-4) },
+        book: { startUsd: tot.startUsd, equityUsd: tot.equityUsd, cashUsd: tot.cashUsd, realizedTodayUsd: round2(st.members.reduce((a, m) => a + (m.book?.realizedTodayUsd ?? 0), 0)) },
+        spend: {
+            todayUsd: st.global.today.modelUsd, dayCapUsd: st.global.caps.modelUsdPerDay, turnsToday: st.global.today.turns,
+            candidateSessionsToday: st.global.today.candidateSessions, positionSessionsToday: st.global.today.positionSessions, allowance: st.global.allowance,
+        },
+        candidates: ids.flatMap((m) => each((s) => s.candidates, m).map((c) => ({ ...c, strategy: m }))),
+        sessions: ids.flatMap((m) => each((s) => s.sessions, m).map((x) => ({ ...x, id: `${m}:${x.id}`, strategy: m }))),
+        positions: ids.flatMap((m) => each((s) => s.positions, m).map((p) => ({ ...p, strategy: m }))),
+        ledgerTail: tails.slice(-12).map((e, i) => ({ seq: i + 1, t: e.t, kind: e.kind, text: `[${e.member}] ${e.text}` })),
+        ledgerHead: '', events: st.members.reduce((a, m) => a + (states.get(m.id)?.events ?? 0), 0),
+        fleet: { fleetId: st.fleetId, strategies: st.members.length, statusPath: '' },
+    };
+}
+export async function fleetRunCmd(argv, io, over = {}) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    if (opts.live) {
+        io.stderr.write('dexterm autotrade run --all: live money is not available; parallel strategies run on paper only (--paper)\n');
+        return 2;
+    }
+    if (!opts.paper) {
+        io.stderr.write(`dexterm autotrade run --all: pass --paper (autotrade runs on paper only)\nusage: ${FLEET_RUN_USAGE}\n`);
+        return 2;
+    }
+    if (pos.length || typeof opts.strategy === 'string') {
+        io.stderr.write(`dexterm autotrade run --all runs every strategy listed in autotrade.json; name no strategy here\nusage: ${FLEET_RUN_USAGE}\n`);
+        return 2;
+    }
+    const home = dextermHome(io.env);
+    const kill = over.killSwitch ?? new KillSwitch();
+    const panic = kill.engaged();
+    if (panic) {
+        io.stderr.write(`dexterm autotrade run --all: the panic switch is engaged (${panic.reason}); nothing starts until you run \`dexterm wallet resume\` in a terminal\n`);
+        return 1;
+    }
+    const rc = loadRunnerConfig(home);
+    if (!rc.ok) {
+        io.stderr.write(`dexterm autotrade run --all: ${rc.path} is invalid:\n${rc.errors.map((e) => `  ${e}`).join('\n')}\n`);
+        return 1;
+    }
+    const runnerCfg = rc.config;
+    const fc = loadFleetConfig(home, typeof opts.config === 'string' ? opts.config : undefined);
+    if (!fc.ok) {
+        io.stderr.write(`dexterm autotrade run --all: ${fc.path}:\n${fc.errors.map((e) => `  ${e}`).join('\n')}\n`);
+        if ('missing' in fc)
+            io.stderr.write('  example:\n  { "schema": "dexterm-autotrade/1",\n    "strategies": [ { "id": "moon-a", "preset": "moonbag", "bankroll": { "usd": 500 } },\n                    { "id": "scalp-b", "preset": "scalp", "bankroll": { "sol": 1 } } ],\n    "global": { "maxConcurrentSessions": 3, "modelUsdPerDay": 10 } }\n  shared paper accounts (many strategies on one simulated wallet, one strategy on many):\n  { "schema": "dexterm-autotrade/1",\n    "accounts": [ { "id": "main", "bankroll": { "usd": 1000 } }, { "id": "yolo", "bankroll": { "sol": 1 } } ],\n    "strategies": [ { "id": "moon", "preset": "moonbag", "account": "main" },\n                    { "id": "scalp", "preset": "scalp", "account": ["main", "yolo"] } ] }\n');
+        return 1;
+    }
+    const fleetCfg = fc.config;
+    const enabled = fleetCfg.strategies.filter((m) => m.enabled);
+    if (!enabled.length) {
+        io.stderr.write(`dexterm autotrade run --all: every strategy in ${fc.path} is "enabled": false; nothing to run\n`);
+        return 1;
+    }
+    const replay = typeof opts.replay === 'string' ? opts.replay : null;
+    const quiet = !!opts.quiet;
+    const say = (s) => { if (!quiet)
+        io.stdout.write(`${s}\n`); };
+    // The market first (a SOL bankroll needs the SOL price before the books are built).
+    let tape;
+    let data = null;
+    if (replay) {
+        try {
+            tape = loadTape(replay);
+        }
+        catch (e) {
+            io.stderr.write(`dexterm autotrade run --all: ${e.message}\n`);
+            return 1;
+        }
+    }
+    else {
+        const rpc = resolveRpcUrl({ env: io.env });
+        data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env), rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
+    }
+    const closeData = () => { try {
+        data?.close();
+    }
+    catch { /* closing */ } };
+    let solUsd = typeof opts['sol-usd'] === 'string' ? num(opts['sol-usd'], NaN) : fleetCfg.solUsd ?? null;
+    if (Number.isNaN(solUsd)) {
+        io.stderr.write('dexterm autotrade run --all: --sol-usd needs a positive number\n');
+        closeData();
+        return 2;
+    }
+    if (solUsd === null && data && (fleetCfg.strategies.some((m) => m.bankroll && 'sol' in m.bankroll) || (fleetCfg.accounts ?? []).some((a) => 'sol' in a.bankroll))) {
+        try {
+            const p = (await data.dexscreener.tokens([SOL_MINT])).get(SOL_MINT)?.pair.priceUsd ?? null;
+            solUsd = p && p > 1 && p < 100_000 ? p : null;
+        }
+        catch {
+            solUsd = null;
+        }
+    }
+    // Every strategy resolves, or nothing starts (fail closed: a typo never leaves one strategy silently out).
+    const members = [];
+    const problems = [];
+    // Shared paper accounts (task-1538): each one's starting balance in USD (a SOL balance at the SOL price).
+    const accounts = [];
+    for (const a of fleetCfg.accounts ?? []) {
+        const b = bankrollUsd(a.bankroll, solUsd);
+        if (b.error || b.usd === null) {
+            problems.push(`paper account ${a.id}: ${b.error ?? 'no balance'}`);
+            continue;
+        }
+        accounts.push({ id: a.id, startUsd: b.usd, ...('sol' in a.bankroll ? { sol: a.bankroll.sol, solUsd: solUsd } : {}) });
+    }
+    const accountOf = new Map(accounts.map((a) => [a.id, a]));
+    for (const m of fleetCfg.strategies) {
+        const r = resolveStrategyArg(m.preset ?? m.file, io);
+        if (!r || !r.ok) {
+            problems.push(`${m.id}: ${r ? r.errors.map((e) => `${e.path || '/'} ${e.msg}`).join('; ') : 'no strategy'}`);
+            continue;
+        }
+        if (r.strategy.mode !== 'paper') {
+            problems.push(`${m.id}: ${r.strategy.id} is mode "${r.strategy.mode}"; the runner refuses anything but paper`);
+            continue;
+        }
+        const acct = m.account ? accountOf.get(m.account) : undefined;
+        if (m.account && !acct)
+            continue; // its account already failed above
+        const b = acct ? { usd: acct.startUsd } : bankrollUsd(m.bankroll, solUsd);
+        if ('error' in b && b.error) {
+            problems.push(`${m.id}: ${b.error}`);
+            continue;
+        }
+        const { strategy, basedOn } = memberStrategy(r.strategy, m, b.usd);
+        const sol = acct ? (acct.sol !== undefined ? { sol: acct.sol, solUsd: acct.solUsd } : {}) : m.bankroll && 'sol' in m.bankroll ? { sol: m.bankroll.sol, solUsd: solUsd } : {};
+        members.push({ config: m, strategy, basedOn, bankroll: { usd: strategy.bankroll.startUsd, ...sol } });
+    }
+    if (problems.length) {
+        io.stderr.write(`dexterm autotrade run --all: nothing started:\n${problems.map((p) => `  ${p}`).join('\n')}\n`);
+        closeData();
+        return 1;
+    }
+    const fleetId = newRunId('fleet');
+    const lock = acquireRunLock(home, fleetId);
+    if (!lock.ok) {
+        io.stderr.write(`dexterm autotrade run --all: another runner is active (pid ${lock.holder.pid}, run ${lock.holder.runId}); stop it first\n`);
+        closeData();
+        return 1;
+    }
+    if (lock.reclaimed)
+        say(`reclaimed a stale runner lock (pid ${lock.reclaimed.pid} is gone)`);
+    if (!clearStaleControl(home, fleetId)) {
+        io.stderr.write(`dexterm autotrade run --all: ${controlPath(home)} cannot be read; look at it and remove it, then start again\n`);
+        releaseRunLock(home, fleetId);
+        closeData();
+        return 1;
+    }
+    clearMemberControls(home, fleetId);
+    const { ledger: fleetLedger, files: fleetFiles } = fileLedger(home, fleetId);
+    const startedAt = Date.now();
+    const guard = new FleetGuard(fleetCfg.global, runnerCfg, { loadavg: over.loadavg });
+    const rawPath = opts.raw ? join(home, 'autotrade', 'runs', `${fleetId}.stream.jsonl`) : null;
+    const sessions = over.sessions ?? (opts.stub
+        ? () => stubSession()
+        : (m, gate, log, clock) => claudeSessionFactory({
+            bin: typeof opts['claude-bin'] === 'string' ? opts['claude-bin'] : (io.env.DEXTERM_CLAUDE_BIN || 'claude'),
+            account: () => prepareAccount(runnerCfg.account, io.env),
+            model: typeof opts.model === 'string' ? opts.model : undefined,
+            systemPrompt: (s) => runnerSystemPrompt(s, { live: !replay }),
+            gate, log,
+            onRaw: rawPath ? (id, line) => appendFileSync(rawPath, `${JSON.stringify({ strategy: m.config.id, sessionId: id, line })}\n`, { mode: 0o600 }) : undefined,
+            now: clock,
+        }));
+    let live = null;
+    let source;
+    let dossier;
+    let vet;
+    if (data) {
+        live = new LiveSource({ store: data.store, dexscreener: data.dexscreener }, { onLog: (l) => fleetLedger.add(Date.now(), 'source_error', { error: l.slice(0, 300) }) });
+        const ls = live;
+        source = { name: 'live keyless data layer (Store + DexScreener tokens/v1 fast lane), shared by every strategy', ticks: ls.ticks(), startT: startedAt, setFocus: (marks) => { ls.setFocus(marks); writeFocus(home, marks); } };
+        // One dossier record per coin per 30 s, whichever strategy asks; each strategy renders its own text.
+        const { McpTools } = await import('../../../mcp/src/index.js');
+        const mcp = new McpTools(data, () => ({ screen: 'autotrade-runner', actions: { mints: [], feeds: [], sortKeys: [] } }));
+        const shared = sharedDossier(async (mint) => {
+            try {
+                return await mcp.call('get_dossier', { mint, interval: '5m' });
+            }
+            catch (e) {
+                return { availability: { present: [], missing: [`dossier: ${e.message}`], knownUnavailable: [] } };
+            }
+        });
+        dossier = () => async (k, h, matched, b) => renderDossierRecord(await shared.get(k.mint), { mint: k.mint, symbol: k.symbol, matched }, k, h, b);
+        // A member's LARP gate (entry.safety.larp, the yolo preset's) on live data, as `autotrade run` has it.
+        vet = fleetLarpVet((mint) => mcp.call('larp_check', { mint }));
+    }
+    // Heartbeat: the aggregate rendezvous, the fleet status, every summary.
+    const states = new Map();
+    const runOf = new Map();
+    const tails = [];
+    let lastStatus = null;
+    let lastWrite = 0;
+    let lastBeatOk = startedAt;
+    let beatFailing = false;
+    const writeAll = (force = false) => {
+        const st = lastStatus;
+        if (!st)
+            return;
+        const now = Date.now();
+        if (!force && now - lastWrite < 1000)
+            return;
+        lastWrite = now;
+        try {
+            const agg = aggregateRendezvous(st, states, tails);
+            agg.fleet.statusPath = fleetStatusPath(home);
+            writeRendezvous(home, { ...agg, heartbeatAt: now });
+            writeJsonAtomic(fleetStatusPath(home), { ...st, heartbeatAt: now });
+            writeJsonAtomic(fleetFiles.summary, { schema: RUN_SUMMARY_SCHEMA, runId: fleetId, strategy: { id: 'parallel', version: `${st.members.length} strategies`, hash: '' }, startedAt, updatedAt: now, state: st.state, book: agg.book, spend: agg.spend, events: fleetLedger.events.length, ledgerHead: fleetLedger.head(), source: st.source });
+            for (const m of st.members) {
+                const s = states.get(m.id);
+                const runId = runOf.get(m.id);
+                if (!s || !runId)
+                    continue;
+                writeJsonAtomic(runFiles(home, runId).summary, { schema: RUN_SUMMARY_SCHEMA, runId, strategy: s.strategy, startedAt: m.startedAt, updatedAt: now, state: s.state, book: s.book, spend: s.spend, events: s.events, ledgerHead: s.ledgerHead, source: st.source, fleetId });
+            }
+            lastBeatOk = now;
+            if (beatFailing) {
+                beatFailing = false;
+                fleetLedger.add(now, 'heartbeat_ok', {});
+            }
+        }
+        catch (e) {
+            if (!beatFailing) {
+                beatFailing = true;
+                fleetLedger.add(now, 'heartbeat_failed', { error: e.message.slice(0, 200) });
+            }
+        }
+    };
+    const beat = setInterval(() => writeAll(true), HEARTBEAT_MS);
+    const maxMin = num(opts['max-minutes'], 0);
+    const stopAt = maxMin ? startedAt + maxMin * 60_000 : Infinity;
+    let stopping = false;
+    const stop = (why) => { if (stopping)
+        return; stopping = true; fleetLedger.add(Date.now(), 'stop_requested', { why }); say(`stopping every strategy (${why}): open sessions close, each paper book is kept in its ledger`); live?.stop(); };
+    const onSig = () => stop('signal');
+    process.once('SIGINT', onSig);
+    process.once('SIGTERM', onSig);
+    const safety = new RunnerSafety({ home, runId: fleetId, killSwitch: kill, heartbeatAgeMs: () => (beatFailing ? Date.now() - lastBeatOk : 0) });
+    say(`dexterm autotrade run --all · PAPER · ${members.length} strategies at once (${enabled.length} enabled) · ${replay ? `replay ${replay}` : 'live keyless data, one feed for all'} · sessions ${opts.stub ? 'stub' : `claude (${runnerCfg.account.kind}${typeof opts.model === 'string' ? `, ${opts.model}` : ''})`}`);
+    if (accounts.length)
+        say(`paper accounts: ${accounts.map((a) => `${a.id} $${a.startUsd}${a.sol !== undefined ? ` (${a.sol} SOL)` : ''} ← ${members.filter((m) => m.config.account === a.id).map((m) => m.config.id).join(', ') || 'no strategy'}`).join(' · ')}`);
+    // The single run's HIGH RISK line (task-1532), for every yolo-like member of the fleet (paper only here).
+    const risky = members.filter((m) => m.strategy.highRisk).map((m) => m.config.id);
+    if (risky.length)
+        say(`⚠ HIGH RISK strateg${risky.length === 1 ? 'y' : 'ies'} (${risky.join(', ')}): one position at a time, early entries, most of them lose. Experimental; can lose all funds; not financial advice.`);
+    say(`fleet ${fleetId} · global caps: ${guard.caps.maxConcurrentSessions} sessions at once, $${guard.caps.modelUsdPerDay}/day model spend, ${guard.caps.candidateSessionsPerDay} candidate sessions/day · ledger ${fleetFiles.ledger}`);
+    let code = 0;
+    try {
+        const res = await runFleet({
+            fleetId, home, members, tape, source, runner: runnerCfg, guard, fleetLedger, fleetLedgerPath: fleetFiles.ledger, ...(accounts.length ? { accounts } : {}),
+            pacing: replay ? { mode: 'paced', msPerTick: num(opts['ms-per-tick'], 2000) } : { mode: 'live' },
+            sessions, dossier, vet, newRunId: (id) => newRunId(id), verbose: true, onLine: say,
+            globalSafety: () => {
+                if (Date.now() >= stopAt)
+                    stop('max-minutes');
+                const v = safety.step();
+                return stopping && !v.halt ? { ...v, halt: 'runner-stopped', detail: 'a signal or --max-minutes', endWhenFlat: true } : v;
+            },
+            hooks: {
+                onMemberEvent: (m, runId, e) => {
+                    runOf.set(m, runId);
+                    if (['candidate', 'fill', 'trade_closed', 'halt', 'refused', 'session_start', 'session_end', 'entries_paused', 'entries_resumed', 'stuck'].includes(e.kind)) {
+                        tails.push({ t: e.t, kind: e.kind, member: m, text: tailLine(e) });
+                        if (tails.length > 48)
+                            tails.splice(0, tails.length - 24);
+                    }
+                    over.hooks?.onMemberEvent?.(m, runId, e);
+                },
+                onMemberState: (m, runId, s) => { runOf.set(m, runId); states.set(m, s); over.hooks?.onMemberState?.(m, runId, s); },
+                onFleetState: (st) => { lastStatus = st; writeAll(st.state === 'stopped'); over.hooks?.onFleetState?.(st); },
+            },
+        });
+        const rows = compareRows(res.status);
+        say('');
+        for (const l of compareTable(rows))
+            say(l);
+        const acctLines = accountTable(res.status);
+        if (acctLines.length) {
+            say('');
+            for (const l of acctLines)
+                say(l);
+        }
+        const tot = fleetTotals(res.status);
+        say(`done · ${members.length} strategies · together ${tot.pnlUsd >= 0 ? '+' : '-'}$${Math.abs(tot.pnlUsd).toFixed(2)} on $${tot.startUsd.toFixed(2)} (paper) · $${tot.spendUsd.toFixed(4)} model spend · fleet ledger head ${fleetLedger.head()}`);
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade run --all: ${e.message}\n`);
+        code = 1;
+    }
+    finally {
+        clearInterval(beat);
+        process.removeListener('SIGINT', onSig);
+        process.removeListener('SIGTERM', onSig);
+        if (lastStatus && lastStatus.state !== 'stopped')
+            lastStatus = { ...lastStatus, state: 'stopped' };
+        writeAll(true);
+        writeFocus(home, []);
+        live?.stop();
+        closeData();
+        clearControl(home, fleetId);
+        clearMemberControls(home, null);
+        releaseRunLock(home, fleetId);
+    }
+    return code;
+}
+/** One short line for the aggregate ledger tail (no message text). */
+function tailLine(e) {
+    const v = (k) => (e[k] === undefined || e[k] === null ? '' : String(e[k]).slice(0, 40));
+    switch (e.kind) {
+        case 'candidate': return `candidate ${v('symbol')}`;
+        case 'fill': return `${v('side')} $${Number(e.usd ?? 0).toFixed(2)} ${v('reason')}`;
+        case 'trade_closed': {
+            const t = e.trade;
+            return `closed ${t?.symbol ?? ''} ${(t?.pnlUsd ?? 0) >= 0 ? '+' : '-'}$${Math.abs(t?.pnlUsd ?? 0).toFixed(2)} by ${t?.exitReason ?? ''}`;
+        }
+        case 'refused': return `refused ${v('rule')}`;
+        default: return [v('reason'), v('sessionId'), v('rule')].filter(Boolean).join(' ') || String(e.kind);
+    }
+}
+/** Candidate + held coins of every strategy for the recorder's tick lane (task-1504 focus file); best effort. */
+function writeFocus(home, marks) {
+    void import('../../../recorder/src/index.js').then((m) => {
+        try {
+            m.writeFocusFile(m.focusFilePath(home), marks.map((x) => ({ mint: x.mint, role: x.role, until: Date.now() + 30 * 60_000 })), Date.now());
+        }
+        catch { /* the recorder is optional */ }
+    }).catch(() => { });
+}
+/**
+ * The fleet's LARP gate per member (entry.safety.larp, e.g. the yolo preset), on live data only, as `autotrade run` has
+ * it: without it a gated strategy would open candidates unchecked under `run --all`. One larp_check per coin for the
+ * whole fleet; each member applies its own maxScore / unknown, and a check that throws is not kept (the next asks again).
+ */
+export function fleetLarpVet(check) {
+    const byMint = new Map();
+    const shared = (mint) => {
+        let p = byMint.get(mint);
+        if (!p) {
+            p = check(mint);
+            byMint.set(mint, p);
+            p.catch(() => byMint.delete(mint));
+        }
+        return p;
+    };
+    return (m) => (m.strategy.entry.safety.larp ? larpVet(m.strategy.entry.safety.larp, shared) : undefined);
+}

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