dexterm-cli 0.1.7 → 0.2.1

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

@@ -10,6 +10,11 @@
 // Nothing here arms a mandate, signs, holds a key or touches a wallet. task-1571: there is no `--live`: dexterm places
 // no live order. Live trading happens in the Telegram trading bot of the user's choice.
 //
+// task-1645: `--real` runs a strategy armed for real mode (`dexterm autotrade signal arm`, on the user's terminal) on
+// LIVE data only: the same engine as paper, and every fill first goes out as a LIVE TRADE FIRE signal (outbox +
+// the channels of connectors.json `signals`, the Telegram copy through the user's bot). Never on a replay (no stale
+// price may ever reach an executor), never with chat approvals (a tap never authorises a real signal).
+//
 // Telegram (task-1527): when `dexterm telegram setup` stored a token and a chat is paired, the user's own bot starts
 // with the run (telegram-host.ts): notify, control through the same control file, and approve-to-trade on paper (a
 // strategy with `entry.decide: "agent+approve"`, or approvals on). --no-telegram keeps it off; an agent+approve
@@ -24,12 +29,17 @@ import { join } from 'node:path';
 import { dextermHome, loadConfig } from '../../../custom/src/index.js';
 import { pickBasis } from '../../../data/src/basis.js';
 import { KillSwitch, createDataLayer, defaultDbPath, resolveRpcUrl } from '../../../data/src/index.js';
+import { DrainPoller, RugProbe, chainVets, defaultFetchJson, rugproofVet } from '../../../autotrade/src/index.js';
 import { HEARTBEAT_MS, LiveSource, badgeOf, RUNNER_RENDEZVOUS_SCHEMA, RunnerSafety, SessionGate, acquireRunLock, clearControl, clearStaleControl, controlPath, claudeSessionFactory, effectiveCaps, fileLedger, loadRunnerConfig, loadTape, newRunId, prepareAccount, releaseRunLock, renderDossierRecord, runAutotrade, runnerRendezvousPath, runnerSystemPrompt, simExecutor, stubSession, writeJsonAtomic, writeRendezvous, RUN_SUMMARY_SCHEMA, builtinTapePath, } from '../../../autotrade/src/index.js';
 import { assertAutotradeAllowed, ollamaSessionFactory } from '../../../autotrade/src/ollama-sessions.js';
+import { Outbox, RealSignalExecutor, channelsFromConfig, enabledChannels, loadSignalsConfig, openRealRun, realModeCheck } from '../../../autotrade/src/index.js';
+import { PaperLimitsExecutor, effectiveLimits, loadLimits } from '../../../autotrade/src/index.js';
+import { digestDue, digestLines, hmacStore, limitsSummary, loadDigestState, saveDigestState, startExecutorListener } from '../../../autotrade/src/index.js';
+import { digestFor } from "./report.js";
 import { parseArgs, resolveStrategyArg } from "./strategies.js";
 import { startTelegramHost } from "./telegram-host.js";
-const BOOL = ['paper', 'live', 'stub', 'verbose', 'quiet', 'raw', 'no-telegram'];
-export const RUN_USAGE = 'dexterm autotrade run <id|file> --paper [--replay TAPE [--ms-per-tick 2000]] [--engine claude|ollama] [--model M] [--max-minutes N] [--stub] [--raw] [--quiet] [--no-telegram]';
+const BOOL = ['paper', 'real', 'live', 'stub', 'verbose', 'quiet', 'raw', 'no-telegram'];
+export const RUN_USAGE = 'dexterm autotrade run <id|file> --paper|--real [--replay TAPE [--ms-per-tick 2000]] [--engine claude|ollama] [--model M] [--max-minutes N] [--sol-usd N] [--stub] [--raw] [--quiet] [--no-telegram]';
 /** task-1571: what `--live` says. dexterm holds no key and places no live order. */
 export const NO_LIVE = 'dexterm autotrade run: there is no --live: dexterm runs strategies on paper only and never holds a key or signs; live trading happens in the Telegram trading bot of your choice (your own bot gets the alerts: dexterm telegram setup)';
 function num(v, dflt) {
@@ -45,8 +55,12 @@ export async function runCmd(argv, io, over = {}) {
         io.stderr.write(`${NO_LIVE}\n`);
         return 2;
     }
-    if (!opts.paper) {
-        io.stderr.write(`dexterm autotrade run: pass --paper (autotrade runs on paper only)\nusage: ${RUN_USAGE}\n`);
+    if (!opts.paper && !opts.real) {
+        io.stderr.write(`dexterm autotrade run: pass --paper (or --real for a strategy armed for real mode)\nusage: ${RUN_USAGE}\n`);
+        return 2;
+    }
+    if (opts.paper && opts.real) {
+        io.stderr.write('dexterm autotrade run: --paper or --real, not both\n');
         return 2;
     }
     const arg = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
@@ -62,11 +76,17 @@ export async function runCmd(argv, io, over = {}) {
             io.stderr.write(`error ${e.path} ${e.msg}\n`);
         return 1;
     }
-    const strategy = r.strategy;
-    if (strategy.mode !== 'paper') {
-        io.stderr.write(`dexterm autotrade run: ${strategy.id} is mode "${strategy.mode}": the runner runs paper only (dexterm holds no key and places no live order)\n`);
+    // task-1645: --paper on a real strategy runs its paper twin (a forward test: no signal goes out).
+    const strategy = opts.paper && r.strategy.mode === 'real' ? { ...r.strategy, mode: 'paper' } : r.strategy;
+    if (opts.real && strategy.mode !== 'real') {
+        io.stderr.write(`dexterm autotrade run: ${strategy.id} is mode "${strategy.mode}": --real needs a strategy armed for real mode (dexterm autotrade signal arm ${strategy.id}, on your own terminal)\n`);
         return 1;
     }
+    if (strategy.mode !== 'paper' && strategy.mode !== 'real') {
+        io.stderr.write(`dexterm autotrade run: ${strategy.id} is mode "${strategy.mode}": the runner runs paper only (dexterm holds no key and places no live order); real mode, which sends signals to your own executor, is armed with dexterm autotrade signal arm\n`);
+        return 1;
+    }
+    const realMode = strategy.mode === 'real';
     const home = dextermHome(io.env);
     // task-1537: the run's lines and the agents' messages speak the user's basis (--price/--mcap/env, config, market cap)
     const basis = pickBasis(loadConfig(home).config.display?.priceMode, io.env);
@@ -83,6 +103,19 @@ export async function runCmd(argv, io, over = {}) {
     }
     const config = cfg.config;
     const replay = typeof opts.replay === 'string' ? opts.replay : null;
+    // task-1645: real mode's preconditions, before anything starts (armed at this hash, caps, kill off, a channel).
+    let real = null;
+    if (realMode) {
+        if (replay) {
+            io.stderr.write('dexterm autotrade run: --real runs on live data only (a replay would send old prices to your executor); replay its paper twin with --paper\n');
+            return 2;
+        }
+        real = await prepareReal(home, strategy, opts, io);
+        if ('error' in real) {
+            io.stderr.write(`dexterm autotrade run: ${real.error}\n`);
+            return 1;
+        }
+    }
     // task-1543: the engine for the sessions: --engine, else ai.json (surfaces.autotrade / provider); auto = claude.
     let local = null;
     if (!opts.stub) {
@@ -100,6 +133,8 @@ export async function runCmd(argv, io, over = {}) {
     const lock = acquireRunLock(home, runId);
     if (!lock.ok) {
         io.stderr.write(`dexterm autotrade run: another runner is active (pid ${lock.holder.pid}, run ${lock.holder.runId}); stop it first\n`);
+        if (real && !('error' in real))
+            real.stop();
         return 1;
     }
     if (lock.reclaimed)
@@ -109,7 +144,7 @@ export async function runCmd(argv, io, over = {}) {
         releaseRunLock(home, runId);
         return 1;
     }
-    const badge = 'PAPER';
+    const badge = realMode ? 'REAL (LIVE TRADE FIRE signals to your executor)' : 'PAPER';
     // Telegram: the user's own bot, when it is set up and paired (or the host a /use switch carried over).
     let host = over.telegramHost ?? null;
     const ownHost = !over.telegramHost;
@@ -127,14 +162,103 @@ export async function runCmd(argv, io, over = {}) {
         else if (!t.quiet)
             say(`telegram: off (${t.why})`);
     }
+    if (realMode && host && (strategy.entry.decide === 'agent+approve' || host.service.broker.required(strategy))) {
+        io.stderr.write(`dexterm autotrade run: approve-to-trade over chat is paper only, so ${strategy.id} cannot take an entry in real mode (entry.decide "agent+approve" or \`dexterm telegram approvals on\`); your executor is the last gate in real mode\n`);
+        if (ownHost)
+            await host.stop();
+        releaseRunLock(home, runId);
+        return 1;
+    }
     if (strategy.entry.decide === 'agent+approve' && !host) {
         io.stderr.write(`dexterm autotrade run: ${strategy.id} needs a one-tap approval for every entry (entry.decide "agent+approve"), and no paired Telegram chat is connected; set it up with \`dexterm telegram setup\`\n`);
         releaseRunLock(home, runId);
         return 1;
     }
+    // task-1654: a paper run obeys the limits only when limits.json has a `paper` scope (a forward test that shows what
+    // real mode would have refused or clamped). Its state is the run's own; real mode's files are never touched.
+    let paperLimits = null;
+    if (!realMode) {
+        paperLimits = await preparePaperLimits(home, strategy, opts, io, !!replay);
+        if (paperLimits && 'error' in paperLimits) {
+            io.stderr.write(`dexterm autotrade run: ${paperLimits.error}\n`);
+            if (host && ownHost)
+                await host.stop();
+            releaseRunLock(home, runId);
+            return 1;
+        }
+    }
     const baseExec = simExecutor(strategy.execution);
     if (host)
         host.attach(runId, strategy, baseExec, solUsdFor);
+    // task-1645: the signal executor wraps the paper path (the host's port when the bot is on), so every fill is first a signal.
+    let realExec = null;
+    let outbox = null;
+    let pumpTimer = null;
+    let digestTimer = null;
+    let listener = null;
+    let bookUsd = strategy.bankroll.startUsd;
+    let paperExec = null;
+    if (paperLimits && !('error' in paperLimits)) {
+        paperExec = new PaperLimitsExecutor({ inner: host ? host.port : baseExec, limits: paperLimits.limits, solUsd: paperLimits.solUsd, bookUsd: () => bookUsd, onTrip: say });
+    }
+    if (real && !('error' in real)) {
+        const sc = real.signals;
+        const tg = host ? async (lines) => {
+            const before = host.service.audit.events.length;
+            await host.service.hub.broadcast({ kind: 'text', badge: 'LIVE', lines }, 'trade_fire');
+            if (host.service.audit.events.slice(before).some((e) => e.kind === 'out_failed'))
+                throw new Error('telegram send failed');
+        } : undefined;
+        const { channels, defer } = channelsFromConfig(home, sc, { telegram: tg, env: io.env });
+        try {
+            outbox = Outbox.open(home, { channels, defer });
+        }
+        catch (e) {
+            io.stderr.write(`dexterm autotrade run: ${e.message}\n`);
+            if (host && ownHost)
+                await host.stop();
+            releaseRunLock(home, runId);
+            return 1;
+        }
+        const swept = openRealRun(outbox, runId, strategy, real.check.arming.accountId).swept;
+        if (swept.length)
+            say(`real mode: sent "halted" (runner-lost) for ${swept.length} earlier run(s) that ended without one`);
+        // task-1654: every limit (the effective set for this strategy + account), and a line to the run log and the
+        // paired chat when the executor goes silent / comes back or a risk limit trips.
+        const notify = (line) => { say(line); if (host)
+            void host.service.hub.broadcast({ kind: 'text', badge: 'LIVE', lines: [line] }, 'real_limits').catch(() => { }); };
+        realExec = new RealSignalExecutor({ home, inner: host ? host.port : baseExec, outbox, strategy, arming: real.check.arming, caps: real.check.caps, limits: real.check.limits.values, notify, runId, ttlSec: sc.ttlSec, solUsd: real.solUsd, bookUsd: () => bookUsd });
+        pumpTimer = setInterval(() => { void outbox.pump().catch(() => { }); }, 1000);
+        if (sc.executor.listenPort) {
+            const store = hmacStore(home, sc, io.env);
+            try {
+                listener = await startExecutorListener({ home, port: sc.executor.listenPort, secret: () => { try {
+                        return store.get();
+                    }
+                    catch {
+                        return null;
+                    } } });
+                say(`real mode: executor listener on 127.0.0.1:${listener.port} (POST /heartbeat, /receipt)`);
+            }
+            catch (e) {
+                say(`real mode: executor listener NOT started (${e.message.slice(0, 80)}); executors can still append to autotrade/real/executor.jsonl`);
+            }
+        }
+    }
+    // task-1654: the scheduled digest (opt-in: dexterm autotrade report --schedule daily|weekly), sent by a run with the bot on.
+    if (host) {
+        const tick = () => {
+            const st = loadDigestState(home);
+            const due = digestDue(st, Date.now());
+            if (!due)
+                return;
+            saveDigestState(home, { ...st, lastSentDay: localDayNow(), lastSentAt: Date.now() });
+            const d = digestFor(home, { period: due, now: Date.now() });
+            void host.service.hub.broadcast({ kind: 'text', badge: realMode ? 'LIVE' : 'PAPER', lines: digestLines(d) }, 'report').catch(() => { });
+        };
+        digestTimer = setInterval(tick, 10 * 60_000);
+        digestTimer.unref?.();
+    }
     const { ledger, files } = fileLedger(home, runId, host?.onLedger);
     const startedAt = Date.now();
     const gate = new SessionGate(effectiveCaps(strategy, config), config.allowanceGuard);
@@ -174,6 +298,7 @@ export async function runCmd(argv, io, over = {}) {
     let live = null;
     let dossier;
     let vet;
+    let drain;
     let closeData = () => { };
     if (replay) {
         try {
@@ -209,6 +334,14 @@ export async function runCmd(argv, io, over = {}) {
         const larp = strategy.entry.safety.larp;
         if (larp)
             vet = larpVet(larp, (mint) => mcp.call('larp_check', { mint }));
+        // task-1748: the rug-proof gates first (read-only probes), then the LARP gate; the drain guard polls held pools.
+        const rp = strategy.entry.safety.rugproof;
+        if (rp) {
+            const probe = new RugProbe({ fetchJson: defaultFetchJson(), rpcUrl: rpc.url });
+            vet = chainVets(rugproofVet(rp, { probe }), vet);
+            if (rp.drainGuard)
+                drain = new DrainPoller(rp.drainGuard, probe, (rec) => log('drain_probe', rec));
+        }
     }
     // Heartbeat + rendezvous: on every state change (throttled to 1 s) and every 10 s regardless.
     let last = null;
@@ -226,7 +359,7 @@ export async function runCmd(argv, io, over = {}) {
         lastWrite = now;
         const { t: _t, ...body } = last;
         try {
-            writeRendezvous(home, { schema: RUNNER_RENDEZVOUS_SCHEMA, pid: process.pid, mode: 'paper', runId, startedAt, heartbeatAt: now, ledgerPath: files.ledger, ...body });
+            writeRendezvous(home, { schema: RUNNER_RENDEZVOUS_SCHEMA, pid: process.pid, mode: realMode ? 'real' : 'paper', runId, startedAt, heartbeatAt: now, ledgerPath: files.ledger, ...body });
             writeJsonAtomic(files.summary, { schema: RUN_SUMMARY_SCHEMA, runId, strategy: body.strategy, startedAt, updatedAt: now, state: body.state, book: body.book, spend: body.spend, events: body.events, ledgerHead: body.ledgerHead, source: replay ? `replay ${replay}` : 'live' });
             lastBeatOk = now;
             if (beatFailing) {
@@ -256,14 +389,23 @@ export async function runCmd(argv, io, over = {}) {
         say(`⚠ HIGH RISK strategy (${strategy.id}): one position at a time, early entries, most of them lose. Paper only; not financial advice.`);
     say(`dexterm autotrade run · ${badge} · strategy ${strategy.id} v${strategy.version} (${strategy.hash}) · ${replay ? `replay ${replay}` : 'live keyless data'} · sessions ${opts.stub ? 'stub' : local ? `ollama (local ${local.model}, profile ${local.level}, $0)` : `claude (${config.account.kind}${typeof opts.model === 'string' ? `, ${opts.model}` : ''})`}`);
     say(`run ${runId} · ledger ${files.ledger} · rendezvous ${runnerRendezvousPath(home)}`);
+    if (realExec && real && !('error' in real)) {
+        say(`REAL MODE · account ${real.check.arming.accountId} · limits ${limitsSummary(real.check.limits.values)} · channels ${enabledChannels(real.signals).join(', ')} · ttl ${Math.min(real.signals.ttlSec, real.check.limits.values.signalTtlSec ?? Infinity)} s · kill: dexterm autotrade signal kill · limits: dexterm autotrade limits show`);
+        const carried = realExec.inherited().length;
+        const elsewhere = realExec.heldElsewhere();
+        if (carried || elsewhere.length)
+            say(`REAL HOLDINGS · ${carried} carried from an earlier run of ${strategy.id} (its exits keep running)${elsewhere.length ? ` · ${elsewhere.length} held by other strategies (${elsewhere.map((h) => `${h.symbol} ${h.strategyId}`).join(', ')}): counted against the open cap, not traded here` : ''}${realExec.holdingsSource === 'rebuilt' ? ' · rebuilt from the outbox' : ''} · dexterm autotrade signal held`);
+    }
+    if (paperExec && paperLimits && !('error' in paperLimits))
+        say(`PAPER LIMITS · the paper scope of limits.json applies · ${limitsSummary(paperLimits.limits)} · dexterm autotrade limits show --mode paper`);
     if (host)
-        say(`telegram: on (your own bot, ${badgeOf(host.port.network)}) · approvals ${strategy.entry.decide === 'agent+approve' ? 'required by the strategy' : 'when turned on'} · /status /pause /kill from your paired chat`);
+        say(`telegram: on (your own bot, ${realMode ? 'LIVE copy of each signal' : badgeOf(host.port.network)}) · approvals ${strategy.entry.decide === 'agent+approve' ? 'required by the strategy' : 'when turned on'} · /status /pause /kill from your paired chat`);
     let switchTo = null;
     let code = 0;
     try {
         const res = await runAutotrade({
-            strategy, basis, tape, source, sessions, gate, dossier, vet, verbose: true, onLine: say, ledger, runId,
-            ...(host ? { executor: host.port, approvals: host.service.broker } : { executor: baseExec }),
+            strategy, basis, tape, source, sessions, gate, dossier, vet, drain, verbose: true, onLine: say, ledger, runId,
+            ...(realExec ? { executor: realExec, real: realExec, ...(host ? { approvals: host.service.broker } : {}) } : paperExec ? { executor: paperExec, maxHoldMinutes: () => paperExec.maxHoldMinutes(), ...(host ? { approvals: host.service.broker } : {}) } : host ? { executor: host.port, approvals: host.service.broker } : { executor: baseExec }),
             pacing: replay ? { mode: 'paced', msPerTick: num(opts['ms-per-tick'], 2000) } : { mode: 'live' },
             // The panic file (`dexterm wallet panic`), a stop / flatten request and a local stop (signal, --max-minutes) all
             // halt: no new entries, sessions close. A signal or --max-minutes also ends the tick stream at once.
@@ -273,7 +415,7 @@ export async function runCmd(argv, io, over = {}) {
                 const v = safety.step();
                 return stopping && !v.halt ? { ...v, halt: 'runner-stopped', detail: 'a signal or --max-minutes' } : v;
             },
-            onState: (st) => { runNow = st.t; last = st; writeState(st.state === 'stopped'); host?.onState(st); },
+            onState: (st) => { runNow = st.t; last = st; bookUsd = st.book.equityUsd; writeState(st.state === 'stopped'); host?.onState(st); },
             onFocus: (marks) => { live?.setFocus(marks); writeFocus(home, marks); },
         });
         const next = host?.takeSwitch() ?? null;
@@ -287,6 +429,35 @@ export async function runCmd(argv, io, over = {}) {
     }
     finally {
         clearInterval(beat);
+        if (pumpTimer)
+            clearInterval(pumpTimer);
+        if (digestTimer)
+            clearInterval(digestTimer);
+        if (listener)
+            await listener.close().catch(() => { });
+        // The runner always says goodbye: idempotent after a normal end, and the only `halted` when the run threw.
+        if (realExec) {
+            realExec.sendHalted(code ? 'runner-error' : 'runner-stopped');
+            // task-1679 (0.2.0 decision): what is still open when a real run ends (stop, kill, time limit, error) is impossible to miss.
+            const open = realExec.openOnAccount();
+            if (open.length) {
+                const line = `REAL POSITIONS STILL OPEN (${open.length}): ${open.map((h) => `${h.symbol} ${h.mint}${h.strategyId === strategy.id ? '' : ` (${h.strategyId})`}`).join(', ')}`;
+                say(line);
+                say('  these positions are still open: manage them in your executor. While no real run of the strategy that holds one is running, dexterm sends NO signal for it, sells included. The next real run of that strategy on this account carries it and its exits fire again (the "halted" signal lists them; dexterm autotrade signal held).');
+                if (host)
+                    void host.service.hub.broadcast({ kind: 'text', badge: 'LIVE', lines: [line, 'these positions are still open: manage them in your executor'] }, 'real_limits').catch(() => { });
+            }
+        }
+        if (outbox) {
+            try {
+                await outbox.pump();
+            }
+            catch { /* pending signals stay in the outbox; they expire by TTL */ }
+            outbox.close();
+        }
+        real?.stop?.();
+        if (paperLimits && !('error' in paperLimits))
+            paperLimits.stop();
         process.removeListener('SIGINT', onSig);
         process.removeListener('SIGTERM', onSig);
         anchorChat('end');
@@ -335,7 +506,7 @@ function writeFocus(home, marks) {
  * task-1543: resolve the session engine. claude = the original path (null here). ollama = the user's local model,
  * allowed only when the local profile allows autotrade (paper) — checked before the run lock.
  */
-async function localEngine(opts, io) {
+export async function localEngine(opts, io) {
     const eng = await import('../../../mcp/src/engine/index.js');
     const loaded = eng.loadAiConfig(io.env);
     const flag = typeof opts.engine === 'string' ? eng.parseEngineChoice(opts.engine) : null;
@@ -411,3 +582,86 @@ export function larpVet(g, check, timeoutMs = 20_000) {
         return { ok: true, note: `LARP score ${score}${band ? ` (${band})` : ''} ≤ ${g.maxScore}` };
     };
 }
+const SOL_MINT = 'So11111111111111111111111111111111111111112';
+/**
+ * task-1645: real mode's preconditions (realModeCheck: armed at this hash, kill off, caps, an executor channel) and
+ * SOL/USD for sizes in SOL: `--sol-usd N`, else the SOL pair on DexScreener (keyless), refreshed every minute.
+ * No SOL price, no run: a signal must state its size in SOL.
+ */
+async function prepareReal(home, s, opts, io) {
+    const sc = loadSignalsConfig(home);
+    if (sc.problems.length)
+        io.stderr.write(`warning: signal channels turned off: ${sc.problems.join('; ')}\n`);
+    const check = realModeCheck(home, s, enabledChannels(sc.config));
+    if (!check.ok)
+        return { error: check.why };
+    const fixed = typeof opts['sol-usd'] === 'string' ? Number(opts['sol-usd']) : null;
+    if (fixed !== null && !(fixed > 1 && fixed < 100_000))
+        return { error: '--sol-usd needs the SOL price in USD' };
+    if (fixed)
+        return { check, signals: sc.config, solUsd: () => fixed, stop: () => { } };
+    const { createDataLayer, defaultDbPath } = await import('../../../data/src/index.js');
+    const data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env) });
+    let px = null;
+    const refresh = async () => { try {
+        const p = (await data.dexscreener.tokens([SOL_MINT])).get(SOL_MINT)?.pair.priceUsd ?? null;
+        if (p && p > 1 && p < 100_000)
+            px = p;
+    }
+    catch { /* keep the last price */ } };
+    await refresh();
+    if (!px) {
+        data.close();
+        return { error: 'no SOL/USD price (DexScreener did not answer); pass --sol-usd N' };
+    }
+    const t = setInterval(() => { void refresh(); }, 60_000);
+    t.unref?.();
+    return { check, signals: sc.config, solUsd: () => px, stop: () => { clearInterval(t); data.close(); } };
+}
+/**
+ * task-1654: the `paper` scope of limits.json for a paper run, or null when there is none (paper ignores the limits
+ * then, exactly as before). Sizes are in SOL, so it needs SOL/USD: `--sol-usd N`, else DexScreener on live data; a
+ * replay needs --sol-usd (today's price is not the tape's). An unreadable or invalid file is only a warning: a
+ * paper run moves no money, and the line says the paper scope was NOT applied.
+ */
+async function preparePaperLimits(home, s, opts, io, replay) {
+    const l = loadLimits(home);
+    if (!l.ok) {
+        if (!('missing' in l && l.missing))
+            io.stderr.write(`warning: paper limits NOT applied: ${l.why}\n`);
+        return null;
+    }
+    const accountId = typeof opts.account === 'string' ? opts.account : '-';
+    const e = effectiveLimits(l.doc, { strategyId: s.id, accountId, mode: 'paper' });
+    if (!e.applies)
+        return null;
+    const fixed = typeof opts['sol-usd'] === 'string' ? Number(opts['sol-usd']) : null;
+    if (fixed !== null && !(fixed > 1 && fixed < 100_000))
+        return { error: '--sol-usd needs the SOL price in USD' };
+    if (fixed)
+        return { limits: e.values, solUsd: () => fixed, stop: () => { } };
+    if (replay)
+        return { error: 'limits.json has a paper scope (sizes in SOL): a replay needs the SOL price of its day, --sol-usd N' };
+    const { createDataLayer, defaultDbPath } = await import('../../../data/src/index.js');
+    const data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env) });
+    let px = null;
+    const refresh = async () => { try {
+        const p = (await data.dexscreener.tokens([SOL_MINT])).get(SOL_MINT)?.pair.priceUsd ?? null;
+        if (p && p > 1 && p < 100_000)
+            px = p;
+    }
+    catch { /* keep the last price */ } };
+    await refresh();
+    if (!px) {
+        data.close();
+        return { error: 'limits.json has a paper scope (sizes in SOL) and there is no SOL/USD price (DexScreener did not answer); pass --sol-usd N' };
+    }
+    const t = setInterval(() => { void refresh(); }, 60_000);
+    t.unref?.();
+    return { limits: e.values, solUsd: () => px, stop: () => { clearInterval(t); data.close(); } };
+}
+/** The local calendar day (the digest schedule's key). */
+function localDayNow(t = Date.now()) {
+    const d = new Date(t);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}