dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/autotrade/examples/executor/signal-cmd-executor.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// dexterm executor reference kit: the --signal-cmd hook (task-1654). DRY RUN: logs what it would do; no wallet code.
+//
+// dexterm runs it once per signal, with no shell, the signal line on stdin and the HMAC in DEXTERM_SIGNAL_SIGNATURE
+// (when a secret is set). Wire it with an absolute path:
+//   dexterm autotrade signal channels --signal-cmd '["/usr/local/bin/node","/path/to/signal-cmd-executor.mjs","--account","main","--secret-file","/path/to/secret"]'
+//
+// Exit codes dexterm reads: 0 acted (dry run) · 3 duplicate (counted delivered) · 2 rejected or expired (never
+// retried) · anything else is retried. A line per signal goes to --log (default autotrade/real/kit-cmd.log).
+
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SeenStore, args, dextermHome, handle, heartbeat, readSecret, realDir } from './kit.mjs';
+
+const a = args();
+if (!a.account) { console.error('usage: signal-cmd-executor.mjs --account ID [--secret-file FILE] [--home DIR]'); process.exit(2); }
+const home = a.home || dextermHome();
+const logFile = a.log || join(realDir(home), 'kit-cmd.log');
+const log = (s) => { try { appendFileSync(logFile, `[${new Date().toISOString()}] ${s}\n`); } catch { /* the exit code still answers */ } };
+const name = String(a.name || 'kit-signal-cmd').slice(0, 32);
+const body = readFileSync(0, 'utf8').trim();
+const seen = new SeenStore(a.state || join(realDir(home), 'kit-cmd-seen.json'));
+const c = handle(body, { accountId: a.account, secret: readSecret(a['secret-file']), requireHmac: !!a['require-hmac'], signature: process.env.DEXTERM_SIGNAL_SIGNATURE ?? null, seen, home, executor: name, log, now: Date.now() });
+try { heartbeat(home, { executor: name, accountId: a.account, lastNonce: seen.maxNonce || null }); } catch { /* optional */ }
+process.exit(c.verdict === 'act' ? 0 : c.verdict === 'duplicate' ? 3 : 2);

package/dist/packages/autotrade/examples/executor/telegram-bot-recipe.md

@@ -0,0 +1,47 @@
+# Recipe: a Telegram trading bot as your executor
+
+Many people already trade memecoins through a Telegram trading bot. That bot holds the wallet and signs the swaps.
+dexterm can drive the decision side, but it can never be the bot and never holds the bot's key.
+
+## Why the Telegram copy alone is not enough
+
+dexterm's Telegram copy of each signal goes to **your** chat, for you to read. A bot cannot read another bot's
+messages, so your trading bot never sees that copy. Something on your side has to hand each signal to the bot.
+
+## The shape that works
+
+```
+dexterm (real mode) --signal--> your small relay (one of the kit executors) --order--> your trading bot
+                     <--receipt--                                          <--fill--
+```
+
+1. Start from one of the kit executors, for example `webhook-executor.mjs`. It already verifies the HMAC, dedupes
+   by nonce, honours the TTL, writes receipts and sends heartbeats.
+2. Replace `act()` in `kit.mjs` with the call your bot offers to accounts that automate it. Depending on the bot
+   that is an HTTP API, a CLI, or a message your own user account sends to it through a Telegram client library.
+   Use only what the bot documents and allows. That code, its credentials and the wallet are yours; keep them out
+   of dexterm's folders.
+3. When the bot answers, write the receipt with the real fill: `status: "executed"` plus `priceUsd`, `sizeSol`,
+   `tokens` and `txSig`, or `rejected` / `failed` with a reason. dexterm then shows how far the real fills were
+   from paper.
+4. Keep the relay's heartbeat running. If the relay or the bot goes quiet longer than your `executorSilenceMin`,
+   dexterm pauses new buy signals and tells you.
+
+## Rules the relay must keep (the kit does)
+
+- It acts only on signals for its own `accountId`.
+- It never acts after `expiresAt`, and it never retries a stale order on its own.
+- It dedupes by `nonce` and `id`, because the same signal can arrive twice.
+- It treats `type: "test"` as a test: there is never an order.
+- On `type: "halted"`, it may cancel the `outstanding` nonces that are still open on its side. `open` lists what
+  dexterm still counts as held.
+- It sizes from its own wallet. `sizeSol` is what dexterm's limits allowed, and `sellFraction` applies to what the
+  bot really holds.
+
+## Before any real money
+
+- Run the relay in dry run first. `dexterm autotrade signal test` must show every channel delivered and the relay's
+  receipt.
+- Set your own limits (`dexterm autotrade limits set …`). The defaults are placeholders: 0.25 SOL per trade, 1 SOL
+  a day, 20 buys, 3 open, stop at -0.5 SOL a day.
+- Keep `dexterm autotrade signal kill` at hand. It stops every signal except one final `halted`.

package/dist/packages/autotrade/examples/executor/webhook-executor.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// dexterm executor reference kit: the WEBHOOK receiver (task-1654). DRY RUN: logs what it would do; no wallet code.
+//
+//   node webhook-executor.mjs --account main [--port 8787] [--secret-file FILE] [--home DIR] [--heartbeat-sec 60]
+//
+// Then point dexterm at it:  dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal
+// and prove the wiring:      dexterm autotrade signal test
+//
+// Answers: 200 acted (dry run) · 409 duplicate (dexterm counts it delivered) · 410 expired · 401 bad signature ·
+// 400 anything else it will not act on. It binds 127.0.0.1 only. Ctrl-C stops it.
+
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { SeenStore, args, dextermHome, handle, heartbeat, readSecret, realDir } from './kit.mjs';
+
+const a = args();
+if (!a.account) { console.error('usage: node webhook-executor.mjs --account ID [--port 8787] [--secret-file FILE] [--home DIR]'); process.exit(2); }
+const home = a.home || dextermHome();
+const secret = readSecret(a['secret-file']);
+const seen = new SeenStore(a.state || join(realDir(home), 'kit-webhook-seen.json'));
+const name = String(a.name || 'kit-webhook').slice(0, 32);
+const log = (s) => console.log(`[${new Date().toISOString()}] ${s}`);
+const o = { accountId: a.account, secret, requireHmac: !!a['require-hmac'], seen, home, executor: name, log };
+
+const server = createServer((req, res) => {
+  if (req.method !== 'POST') { res.writeHead(405); res.end('POST only'); return; }
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', (c) => { body += c; if (body.length > 64 * 1024) req.destroy(); });
+  req.on('end', () => {
+    const c = handle(body, { ...o, signature: req.headers['x-dexterm-signature'] ?? null, now: Date.now() });
+    const code = c.verdict === 'act' ? 200 : c.verdict === 'duplicate' ? 409 : c.verdict === 'expired' ? 410 : /^signature/.test(c.why ?? '') ? 401 : 400;
+    res.writeHead(code, { 'content-type': 'text/plain' });
+    res.end(c.verdict);
+  });
+});
+
+const beat = () => { try { heartbeat(home, { executor: name, accountId: a.account, lastNonce: seen.maxNonce || null }); } catch (e) { log(`heartbeat failed: ${e.message}`); } };
+server.listen(Number(a.port ?? 8787), '127.0.0.1', () => {
+  const port = server.address().port;
+  log(`dexterm kit webhook executor (DRY RUN) listening on http://127.0.0.1:${port}/signal · account ${a.account} · HMAC ${secret ? 'checked' : 'NOT checked (no --secret-file)'}`);
+  beat();
+});
+const timer = setInterval(beat, Math.max(5, Number(a['heartbeat-sec'] ?? 60)) * 1000);
+const stop = () => { clearInterval(timer); server.close(() => process.exit(0)); };
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);

package/dist/packages/autotrade/src/account.js

@@ -0,0 +1,74 @@
+// dexterm autotrade — which Claude account a session runs on (task-1505 AT-3, AUTOTRADE-SPEC §7.3).
+//
+// App code ships the account KINDS and the env-var names only; which account is used is the user's runner.json.
+//
+//   native       the user's default `claude` login. Nothing is added; inherited key/token variables are removed
+//                so a stray ANTHROPIC_API_KEY in the shell cannot silently switch the account.
+//   oauth-token  a long-lived Claude login token, fetched at spawn from a helper command or a keychain item and
+//                handed to `claude` on file descriptor 3 (CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR=3). It is never
+//                put in argv, a file, the environment or the ledger.
+//   config-dir   CLAUDE_CONFIG_DIR=<dir>: a separate Claude config with its own login (an empty one answers
+//                "Not logged in"; it never falls back to the native login).
+//   api-key      a pay-as-you-go key from a helper or the keychain, in the child's environment only.
+//
+// Proof per session: the init event's `apiKeySource` must be one of `expectApiKeySource` for the kind, else the
+// session is ended before its first turn. Measured on the native OAuth login: `none` (task-1498). The other kinds'
+// values are the expected ones (an OAuth token or a config-dir login is not an API key; a key is reported as
+// ANTHROPIC_API_KEY) and can be overridden per machine in runner.json once measured there. The check catches a
+// switch between key and login; it cannot tell two OAuth logins apart (the init event names no account).
+import { execFile } from 'node:child_process';
+export const EXPECTED_API_KEY_SOURCE = {
+    native: ['none'],
+    'oauth-token': ['none'],
+    'config-dir': ['none'],
+    'api-key': ['ANTHROPIC_API_KEY'],
+};
+/** Variables that select an account; removed from the child env unless the kind sets them itself. */
+export const ACCOUNT_ENV_VARS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR'];
+export const TOKEN_FD = 3;
+/** Run a helper command (no shell) or read a keychain item; stdout is the secret, trimmed. */
+export const fetchSecret = (src) => new Promise((resolve, reject) => {
+    const [bin, args] = 'command' in src
+        ? [src.command[0], src.command.slice(1)]
+        : ['security', ['find-generic-password', '-w', '-s', src.keychain.service, ...(src.keychain.account ? ['-a', src.keychain.account] : [])]];
+    if (!bin) {
+        reject(new Error('empty secret command'));
+        return;
+    }
+    execFile(bin, args, { timeout: 10_000, maxBuffer: 64 * 1024, env: process.env }, (err, stdout) => {
+        // The helper's stderr and our error text never carry the secret; stdout is never echoed.
+        if (err) {
+            reject(new Error(`the account's secret source failed (${'command' in src ? 'helper command' : 'keychain item'}: ${err.code ?? 'exit'})`));
+            return;
+        }
+        const v = String(stdout).trim();
+        if (!v) {
+            reject(new Error('the account\'s secret source printed nothing'));
+            return;
+        }
+        resolve(v);
+    });
+});
+/** Build the env (and fd secret) for one `claude` spawn. `base` is the runner's own environment. */
+export async function prepareAccount(cfg, base, fetch = fetchSecret) {
+    const env = { ...base };
+    for (const k of ACCOUNT_ENV_VARS)
+        delete env[k];
+    const expectApiKeySource = cfg.expectApiKeySource?.length ? cfg.expectApiKeySource : EXPECTED_API_KEY_SOURCE[cfg.kind];
+    switch (cfg.kind) {
+        case 'native':
+            return { kind: 'native', env, fdSecret: null, expectApiKeySource, label: 'native' };
+        case 'config-dir':
+            env.CLAUDE_CONFIG_DIR = cfg.dir;
+            return { kind: 'config-dir', env, fdSecret: null, expectApiKeySource, label: `config-dir ${cfg.dir}` };
+        case 'oauth-token': {
+            const token = await fetch(cfg.source);
+            env.CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR = String(TOKEN_FD);
+            return { kind: 'oauth-token', env, fdSecret: Buffer.from(token, 'utf8'), expectApiKeySource, label: 'oauth-token' };
+        }
+        case 'api-key': {
+            env.ANTHROPIC_API_KEY = await fetch(cfg.source);
+            return { kind: 'api-key', env, fdSecret: null, expectApiKeySource, label: 'api-key' };
+        }
+    }
+}

package/dist/packages/autotrade/src/backtest.js

@@ -0,0 +1,358 @@
+// dexterm autotrade — backtest + parameter sweep (task-1498 spike, AUTOTRADE-SPEC §3).
+//
+// A backtest is the run loop over a recorded tape with the same engine, clamp and monitor a paper run uses
+// (no separate "backtest logic" to drift). The report gives P/L, win rate, drawdown and per-rule attribution
+// (which exit rule closed what, which trigger opened it, which clamp fired), and always prints the limits of
+// the data next to the numbers.
+//
+// Sweeps follow the skill-care methodology: split the tape CHRONOLOGICALLY by first sighting (the newest
+// 30 % of coins is the held-out TEST, fixed before any tuning; no coin is in both halves), tune on TRAIN only,
+// then report TEST for the winner against the unchanged strategy. Below SKILL_MIN_N test trades the verdict
+// is "too few trades" whatever the numbers say.
+//
+// task-1503 (AT-1, spec §3a): the moonbag lives on a rare tail, so the report also carries the per-entry
+// expectancy with a bootstrap 95% interval, the exit-multiple quantiles, an every-candidate evaluation copy
+// (fixed unit size, book caps lifted, so every entry is an independent sample) and runner recall (of the coins
+// that later ran >= Nx, which did the entry rules pass, what refused the rest, which exit closed the entered).
+// Verdict rule 6: no tuning claim unless train and test both have >= SKILL_MIN_N trades AND the held-out net is
+// above 0 (a loser that loses less does not "win").
+import { SKILL_MIN_N, wilson } from '../../packs/src/index.js';
+import { EntryRules } from "./engine.js";
+import { runAutotrade } from "./runner.js";
+import { validateStrategy, round } from "./strategy.js";
+export const DATA_LIMITS = [
+    'Price path = recorder snapshots (~2-min cadence while listed, written on >= 5% moves or every 30 min), not candles or trades: intrabar spikes and dips are invisible, so stops and take-profits fill at the next recorded price.',
+    'Fills are modelled (constant-product impact on half the recorded liquidity + fee + slippage + network fee), not Jupiter quotes.',
+    'Survivorship: only coins the app recorded (on a screen or in a feed) are in the tape; coins nobody saw are absent.',
+    'Rugs: when liquidity falls under the exit floor the bag cannot be sold (stuck) and is valued at 0 unless liquidity returns; a rug between two rows fills at whatever the next row says (often -99%), never at the level a rule wanted.',
+    'Early entries look later than they are: a young pair enters the tape only once a feed lists it, and pairs that rugged before any feed saw them are missing, so the measured rug rate is a floor.',
+    'Narrative, followed-wallet, social and dev-sell signals are not in the recorded history, so those triggers and exits never fire in a backtest.',
+    'Mechanical entries (no agent): a lockstep backtest has no agent latency and no agent judgement; agent backtests cost Claude usage and stay small-n.',
+];
+/** A closed trade at or below this is counted as a rug (the challenge's rugAtPct). */
+export const RUG_PCT = -80;
+export async function backtest(strategy, tape, sessions = null) {
+    // task-1645: a strategy in mode real backtests as its paper twin (a backtest never emits a trade-fire signal).
+    const run = await runAutotrade({ strategy: strategy.mode === 'real' ? { ...strategy, mode: 'paper' } : strategy, tape, sessions, pacing: { mode: 'lockstep' } });
+    return { report: report(strategy, tape, run), run };
+}
+export function report(s, tape, run) {
+    // Positions still open at the end are closed at their liquidation mark (0 when stuck) for the totals.
+    const recovered = (fills) => fills.some((f) => f.reason === 'cost-recovery');
+    const closed = run.trades.map((t) => ({ pnl: t.pnlUsd, pct: t.pnlPct, exit: t.exitReason, profile: t.profileId, trig: t.entryTrigger, stuck: t.stuck, cost: t.costUsd, recovered: recovered(t.fills) }));
+    for (const p of run.openAtEnd) {
+        const pos = run.book.open.get(p.mint);
+        const pnl = p.markUsd + pos.realizedUsd - pos.costUsd;
+        closed.push({ pnl, pct: round((pnl / pos.costUsd) * 100), exit: p.stuck ? 'end-stuck' : 'end-of-tape', profile: pos.profileId, trig: [], stuck: p.stuck, cost: pos.costUsd, recovered: recovered(pos.fills) });
+    }
+    const best = closed.length ? closed.reduce((a, t) => (t.pnl > a.pnl ? t : a)) : null;
+    const wins = closed.filter((t) => t.pnl > 0);
+    const losses = closed.filter((t) => t.pnl <= 0);
+    const net = closed.reduce((a, t) => a + t.pnl, 0);
+    const gw = wins.reduce((a, t) => a + t.pnl, 0);
+    const gl = -losses.reduce((a, t) => a + t.pnl, 0);
+    const bucket = (key) => {
+        const out = {};
+        for (const t of closed)
+            for (const k of key(t)) {
+                const b = (out[k] ??= { n: 0, pnlUsd: 0 });
+                b.n++;
+                b.pnlUsd = round(b.pnlUsd + t.pnl);
+            }
+        return out;
+    };
+    const avg = (xs) => (xs.length ? round(xs.reduce((a, b) => a + b, 0) / xs.length) : null);
+    const w = wilson(wins.length, closed.length);
+    const first = tape.ticks[0]?.t, last = tape.ticks[tape.ticks.length - 1]?.t;
+    return {
+        strategy: { id: s.id, version: s.version, hash: s.hash },
+        tape: { source: tape.source, mints: tape.mints.length, ticks: tape.ticks.length, from: first ? new Date(first).toISOString() : null, to: last ? new Date(last).toISOString() : null },
+        trades: closed.length, wins: wins.length, losses: losses.length,
+        winRate: w ? { value: round(w.value * 100, 1), lo: round(w.lo * 100, 1), hi: round(w.hi * 100, 1) } : null,
+        netUsd: round(net), netPct: round((net / s.bankroll.startUsd) * 100),
+        profitFactor: gl > 0 ? round(gw / gl) : null,
+        avgWinPct: avg(wins.map((t) => t.pct)), avgLossPct: avg(losses.map((t) => t.pct)),
+        worstPct: closed.length ? Math.min(...closed.map((t) => t.pct)) : null, bestPct: closed.length ? Math.max(...closed.map((t) => t.pct)) : null,
+        maxDrawdownPct: run.maxDrawdownPct,
+        tail: {
+            rugs: closed.filter((t) => t.pct <= RUG_PCT || t.stuck).length, costRecovered: closed.filter((t) => t.recovered).length, netWithoutBestUsd: round(net - (best?.pnl ?? 0)), bestMultiple: best ? round((best.pnl + best.cost) / best.cost) : null,
+            perEntry: bootstrapMean(closed.map((t) => (t.pnl / t.cost) * 100)),
+            multiples: closed.length ? (() => { const m = closed.map((t) => (t.pnl + t.cost) / t.cost).sort((a, b) => a - b); return { p50: round(quantile(m, 0.5)), p90: round(quantile(m, 0.9)), max: round(m[m.length - 1]) }; })() : null,
+        },
+        stuck: closed.filter((t) => t.stuck).length, openAtEnd: run.openAtEnd.length,
+        candidates: run.candidates, sessions: run.sessions, sessionCostUsd: round(run.sessionCostUsd, 4),
+        byExit: bucket((t) => [t.exit]), byProfile: bucket((t) => [t.profile]), byTrigger: bucket((t) => (t.trig.length ? t.trig : ['(open at end)'])),
+        clamps: run.clamps, refusals: run.refusals,
+        limits: DATA_LIMITS,
+    };
+}
+export function renderReport(r) {
+    const usd = (x) => `${x >= 0 ? '+' : '-'}$${Math.abs(x).toFixed(2)}`;
+    const rows = (o) => Object.entries(o).sort((a, b) => b[1].n - a[1].n).map(([k, b]) => `    ${k.padEnd(22)} ${String(b.n).padStart(4)}  ${usd(b.pnlUsd)}`).join('\n');
+    return [
+        `BACKTEST ${r.strategy.id} v${r.strategy.version} (${r.strategy.hash}) · PAPER · recorded data`,
+        `tape: ${r.tape.mints} coins, ${r.tape.ticks} rows, ${r.tape.from ?? '—'} → ${r.tape.to ?? '—'}`,
+        `trades ${r.trades} · wins ${r.wins} · losses ${r.losses} · win rate ${r.winRate ? `${r.winRate.value}% (95% ${r.winRate.lo}–${r.winRate.hi}%)` : '—'}`,
+        `net ${usd(r.netUsd)} (${r.netPct}% of the bankroll) · profit factor ${r.profitFactor ?? '—'} · avg win ${r.avgWinPct ?? '—'}% · avg loss ${r.avgLossPct ?? '—'}% · best ${r.bestPct ?? '—'}% · worst ${r.worstPct ?? '—'}%`,
+        `tail: rugs (<= ${RUG_PCT}% or stuck) ${r.tail.rugs} · cost taken back ${r.tail.costRecovered} · net without the best trade ${usd(r.tail.netWithoutBestUsd)} · best trade ${r.tail.bestMultiple ?? '—'}x its cost`,
+        `      per entry ${r.tail.perEntry ? `${r.tail.perEntry.meanPct}% of the stake (bootstrap 95% ${r.tail.perEntry.lo}% to ${r.tail.perEntry.hi}%)` : '—'} · exit multiple P50 ${r.tail.multiples?.p50 ?? '—'}x · P90 ${r.tail.multiples?.p90 ?? '—'}x · max ${r.tail.multiples?.max ?? '—'}x`,
+        `max drawdown ${r.maxDrawdownPct}% · stuck (unsellable) ${r.stuck} · open at end ${r.openAtEnd} · candidates ${r.candidates} · sessions ${r.sessions} ($${r.sessionCostUsd})`,
+        '  by exit rule:', rows(r.byExit),
+        '  by profile:', rows(r.byProfile),
+        '  by entry trigger:', rows(r.byTrigger),
+        `  clamps fired: ${Object.entries(r.clamps).map(([k, n]) => `${k} ×${n}`).join(', ') || 'none'}`,
+        `  entries refused: ${Object.entries(r.refusals).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([k, n]) => `${k} ×${n}`).join(', ') || 'none'}`,
+        r.trades < SKILL_MIN_N ? `  NOTE: ${r.trades} trades is below n = ${SKILL_MIN_N}: read the counts, not the rates.` : '',
+        '  limits of this data:', ...r.limits.map((l) => `    - ${l}`),
+    ].filter(Boolean).join('\n');
+}
+// ───────────────────────────── held-out split + sweep ─────────────────────────────
+/** Chronological split by each coin's first row: the newest `testFrac` of coins is TEST. */
+export function splitTape(tape, testFrac = 0.3) {
+    const first = new Map();
+    for (const k of tape.ticks)
+        if (!first.has(k.mint))
+            first.set(k.mint, k.t);
+    const order = [...first.entries()].sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1));
+    const nTest = Math.max(1, Math.round(order.length * testFrac));
+    const testSet = new Set(order.slice(order.length - nTest).map(([m]) => m));
+    const cutoff = order[order.length - nTest]?.[1] ?? 0;
+    const pick = (inTest) => ({
+        source: `${tape.source} [${inTest ? 'test' : 'train'}]`,
+        ticks: tape.ticks.filter((k) => testSet.has(k.mint) === inTest),
+        mints: tape.mints.filter((m) => testSet.has(m) === inTest),
+    });
+    return { train: pick(false), test: pick(true), cutoff };
+}
+export function withParams(s, params) {
+    const doc = JSON.parse(JSON.stringify({ ...s, hash: undefined, exits: { default: s.exits.default, profiles: Object.values(s.exits.profiles) } }));
+    delete doc.hash;
+    for (const [path, v] of Object.entries(params)) {
+        const parts = path.split('.');
+        let o = doc;
+        if (parts[0] === 'profile') {
+            o = doc.exits.profiles.find((p) => p.id === s.exits.default);
+            parts.shift();
+        }
+        for (const p of parts.slice(0, -1)) {
+            const next = o[p];
+            if (next === null || typeof next !== 'object')
+                throw new Error(`sweep path ${path}: ${p} is not an object`);
+            o = next;
+        }
+        o[parts[parts.length - 1]] = v;
+    }
+    const r = validateStrategy(doc);
+    if (!r.ok)
+        throw new Error(`sweep params ${JSON.stringify(params)} make the strategy invalid: ${r.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}`);
+    return r.strategy;
+}
+const pickR = (r) => ({ trades: r.trades, netUsd: r.netUsd, maxDrawdownPct: r.maxDrawdownPct, winRate: r.winRate });
+/** Seeded PRNG (mulberry32) so a random sweep is reproducible. */
+export function rng(seed) {
+    let a = seed >>> 0;
+    return () => { a = (a + 0x6d2b79f5) >>> 0; let t = a; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+export function combos(grid, mode, max, seed = 1) {
+    const keys = Object.keys(grid);
+    let all = [{}];
+    for (const k of keys)
+        all = all.flatMap((c) => grid[k].map((v) => ({ ...c, [k]: v })));
+    if (mode === 'grid')
+        return all.slice(0, max);
+    const r = rng(seed);
+    const out = [];
+    const pool = [...all];
+    while (out.length < max && pool.length)
+        out.push(pool.splice(Math.floor(r() * pool.length), 1)[0]);
+    return out;
+}
+export async function sweep(s, tape, grid, o = {}) {
+    const { train, test, cutoff } = splitTape(tape, o.testFrac ?? 0.3);
+    const rows = [];
+    const invalid = [];
+    for (const params of combos(grid, o.mode ?? 'grid', o.max ?? 64, o.seed ?? 1)) {
+        let st;
+        // A combination the validator refuses (e.g. TP1 above TP2) is skipped and counted, never run.
+        try {
+            st = withParams(s, params);
+        }
+        catch (e) {
+            invalid.push({ params, error: e.message.replace(/^.*invalid: /, '') });
+            continue;
+        }
+        rows.push({ params, train: pickR((await backtest(st, train)).report) });
+    }
+    if (!rows.length)
+        throw new Error('every sweep combination is invalid');
+    const minN = o.minTrainTrades ?? 5;
+    const eligible = rows.filter((r) => r.train.trades >= minN);
+    const best = [...(eligible.length ? eligible : rows)].sort((a, b) => b.train.netUsd - a.train.netUsd || a.train.maxDrawdownPct - b.train.maxDrawdownPct)[0];
+    // TEST is touched exactly twice: the unchanged strategy and the train winner.
+    const baseline = { params: {}, train: pickR((await backtest(s, train)).report), test: pickR((await backtest(s, test)).report) };
+    best.test = pickR((await backtest(withParams(s, best.params), test)).report);
+    const verdict = sweepVerdict(best, baseline);
+    return {
+        split: { trainMints: train.mints.length, testMints: test.mints.length, cutoff: new Date(cutoff).toISOString() },
+        combos: rows.length, invalid, baseline, best, top: [...rows].sort((a, b2) => b2.train.netUsd - a.train.netUsd).slice(0, 5), verdict,
+    };
+}
+/**
+ * Verdict rule 6 (§3a): gain wording only when TRAIN and TEST both have >= SKILL_MIN_N trades, the held-out net
+ * is above 0, the winner beats the unchanged strategy on TEST, and train agrees. A loser that loses less is
+ * reported as exactly that, never as a gain.
+ */
+export function sweepVerdict(best, baseline) {
+    const t = best.test, b = baseline.test;
+    if (best.train.trades < SKILL_MIN_N || t.trades < SKILL_MIN_N)
+        return `too few trades (train ${best.train.trades}, held-out ${t.trades}; both need >= ${SKILL_MIN_N}): no tuning claim`;
+    if (t.netUsd <= 0) {
+        return t.netUsd > b.netUsd
+            ? `no edge: the tuned strategy still loses on the held-out coins (${t.netUsd.toFixed(2)} USD; it only loses ${(t.netUsd - b.netUsd).toFixed(2)} USD less than unchanged): no tuning claim`
+            : `no edge: the held-out net is ${t.netUsd.toFixed(2)} USD (unchanged ${b.netUsd.toFixed(2)}): keep the strategy as is`;
+    }
+    if (t.netUsd > b.netUsd && best.train.netUsd > baseline.train.netUsd)
+        return `held-out gain ${(t.netUsd - b.netUsd).toFixed(2)} USD over the unchanged strategy, held-out net ${t.netUsd.toFixed(2)} USD (train and test agree)`;
+    return `no held-out gain (test ${t.netUsd.toFixed(2)} vs unchanged ${b.netUsd.toFixed(2)}): keep the strategy as is`;
+}
+export function renderSweep(r) {
+    const usd = (x) => `${x >= 0 ? '+' : '-'}$${Math.abs(x).toFixed(2)}`;
+    const row = (x) => `${JSON.stringify(x.params)}  train ${x.train.trades} trades ${usd(x.train.netUsd)} dd ${x.train.maxDrawdownPct}%${x.test ? `  · held-out ${x.test.trades} trades ${usd(x.test.netUsd)} dd ${x.test.maxDrawdownPct}%` : ''}`;
+    return [
+        `SWEEP · PAPER · recorded data · split by first sighting: train ${r.split.trainMints} coins, held-out ${r.split.testMints} coins (newest, from ${r.split.cutoff})`,
+        `combinations run ${r.combos} · refused as invalid ${r.invalid.length}`,
+        `  unchanged:   ${row(r.baseline)}`,
+        `  train best:  ${row(r.best)}`,
+        '  top 5 on train:', ...r.top.map((x) => `    ${row(x)}`),
+        `VERDICT: ${r.verdict}`,
+        '  The held-out coins were touched twice (the unchanged strategy and the train winner); nothing was tuned on them.',
+    ].join('\n');
+}
+// ───────────────────────────── tail statistics ─────────────────────────────
+export function quantile(sorted, q) {
+    if (!sorted.length)
+        return NaN;
+    const i = (sorted.length - 1) * q;
+    const lo = Math.floor(i), hi = Math.ceil(i);
+    return sorted[lo] + (sorted[hi] - sorted[lo]) * (i - lo);
+}
+/** Mean with a seeded percentile-bootstrap 95% interval (deterministic: same trades → same interval). */
+export function bootstrapMean(xs, resamples = 2000, seed = 1) {
+    if (!xs.length)
+        return null;
+    const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+    const r = rng(seed);
+    const means = [];
+    for (let b = 0; b < resamples; b++) {
+        let sum = 0;
+        for (let i = 0; i < xs.length; i++)
+            sum += xs[Math.floor(r() * xs.length)];
+        means.push(sum / xs.length);
+    }
+    means.sort((a, b) => a - b);
+    return { meanPct: round(mean), lo: round(quantile(means, 0.025)), hi: round(quantile(means, 0.975)) };
+}
+// ───────────────────────────── every-candidate evaluation copy ─────────────────────────────
+/**
+ * The every-candidate copy (§3a run b): each candidate is entered at a fixed unit size with the book caps lifted
+ * (exposure, concurrency, day count, day-loss halt, drawdown size-down and halt, loss-streak cooldown), on a
+ * book large enough that cash never binds. The strategy's own entry rules, per-coin rules, exit profiles and the
+ * fill model are unchanged, so every entry is an independent sample and the result does not depend on which
+ * candidates happened to arrive first. An evaluation copy, never a strategy to run.
+ */
+export function everyCandidate(s, unitUsd = 20) {
+    const doc = JSON.parse(JSON.stringify({ ...s, hash: undefined, exits: { default: s.exits.default, profiles: Object.values(s.exits.profiles) } }));
+    doc.id = `${s.id.slice(0, 21)}-every`;
+    doc.name = 'Every candidate (evaluation copy)';
+    doc.description = `Evaluation copy of ${s.id}: every candidate entered at a fixed $${unitUsd} with the book caps lifted, so each entry is an independent sample.`;
+    doc.bankroll = { ...doc.bankroll, startUsd: 100_000 };
+    doc.sizing = { ...doc.sizing, mode: 'fixed', fixedUsd: unitUsd, maxUsd: unitUsd, minUsd: Math.min(doc.sizing.minUsd, unitUsd), ladder: undefined };
+    delete doc.sizing.pct;
+    delete doc.sizing.riskPct;
+    delete doc.sizing.confidence;
+    delete doc.sizing.ladder;
+    const r = doc.risk;
+    doc.risk = {
+        ...r,
+        dailyLossHaltPct: 100,
+        drawdown: { sizeDownAtPct: 99, sizeDownMult: 1, recoverBelowPct: 0, haltAtPct: 100 },
+        maxConcurrent: 20, maxExposurePct: 100, maxEntriesPerDay: 500,
+        lossStreak: { losses: 50, cooldownMin: 0 },
+        ...(r.recoveredBags ? { recoveredBags: { ...r.recoveredBags, maxBags: 50 } } : {}),
+    };
+    const v = validateStrategy(doc);
+    if (!v.ok)
+        throw new Error(`every-candidate copy of ${s.id} is invalid: ${v.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}`);
+    return v.strategy;
+}
+/**
+ * Runner recall (§3a item 3). A coin is in the window while its age is inside the strategy's entry age range and
+ * its liquidity is at least the default profile's fit.minLiquidityUsd. Its peak is the best price at that
+ * liquidity from the first window row on, divided by the first window row's price. For each threshold: how many
+ * such coins ran >= Nx, how many the entry rules passed on some window row, which rule refused the others (a coin
+ * counts once per rule) and which exit closed each one the run entered.
+ */
+export function runnerRecall(s, tape, run, thresholds) {
+    const rules = new EntryRules(s);
+    const minLiq = s.exits.profiles[s.exits.default].fit.minLiquidityUsd;
+    const { min, max } = s.entry.ageHours;
+    const byMint = new Map();
+    for (const k of tape.ticks) {
+        const a = byMint.get(k.mint);
+        if (a)
+            a.push(k);
+        else
+            byMint.set(k.mint, [k]);
+    }
+    const trades = new Map();
+    for (const t of run.trades)
+        if (!trades.has(t.mint))
+            trades.set(t.mint, { exit: t.exitReason, pnlPct: t.pnlPct, sells: t.fills.slice(1).map((f) => `${f.reason} ${(f.price / t.fills[0].price).toFixed(2)}x`) });
+    for (const p of run.openAtEnd)
+        if (!trades.has(p.mint))
+            trades.set(p.mint, { exit: p.stuck ? 'end-stuck' : 'end-of-tape', pnlPct: null, sells: [] });
+    const coins = [];
+    for (const [mint, ks] of byMint) {
+        const win = ks.filter((k) => k.kind === 'live' && k.createdAt !== null && k.price && (k.liq ?? 0) >= minLiq && (k.t - k.createdAt) / 3600e3 >= min && (max === null || (k.t - k.createdAt) / 3600e3 <= max));
+        if (!win.length)
+            continue;
+        const p0 = win[0].price;
+        const peak = Math.max(...ks.filter((k) => k.t >= win[0].t && (k.liq ?? 0) >= minLiq && k.price).map((k) => k.price));
+        const res = win.map((k) => rules.screen(k));
+        const refusedBy = {};
+        for (const r of res)
+            if (!r.pass)
+                for (const f of r.failed)
+                    refusedBy[f] = (refusedBy[f] ?? 0) + 1;
+        coins.push({ mint, symbol: ks[0].symbol, peakX: round(peak / p0, 1), windowRows: win.length, passed: res.some((r) => r.pass), refusedBy, trade: trades.get(mint) ?? null });
+    }
+    return thresholds.map((x) => {
+        const rs = coins.filter((c) => c.peakX >= x).sort((a, b) => b.peakX - a.peakX);
+        const refusedBy = {};
+        for (const c of rs)
+            if (!c.passed)
+                for (const f of Object.keys(c.refusedBy))
+                    refusedBy[f] = (refusedBy[f] ?? 0) + 1;
+        const exits = {};
+        for (const c of rs)
+            if (c.trade)
+                exits[c.trade.exit] = (exits[c.trade.exit] ?? 0) + 1;
+        return { minX: x, runners: rs.length, passed: rs.filter((c) => c.passed).length, entered: rs.filter((c) => c.trade).length, closedGreen: rs.filter((c) => (c.trade?.pnlPct ?? 0) > 0).length, refusedBy, exits, coins: rs };
+    });
+}
+export function renderRecall(rs, s) {
+    const L = [];
+    const top = (o) => Object.entries(o).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(', ') || 'none';
+    for (const r of rs) {
+        L.push(`RUNNER RECALL >= ${r.minX}x (${s.id}: coins in its entry window that later ran >= ${r.minX}x at sellable liquidity): ${r.runners} · entry rules passed ${r.passed} · entered ${r.entered} · closed green ${r.closedGreen}`);
+        L.push(`  refused runners by rule (a coin counts once per rule): ${top(r.refusedBy)}`);
+        L.push(`  how the entered runners closed: ${top(r.exits)}`);
+        for (const c of r.coins.slice(0, 25)) {
+            const short = `${c.mint.slice(0, 4)}…${c.mint.slice(-4)}`;
+            const why = c.passed ? 'PASSED ' : `refused ${Object.entries(c.refusedBy).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([f, n]) => `${f} ${n}/${c.windowRows}`).join(', ')}`;
+            const tr = c.trade ? ` · ${c.trade.sells.join(' → ') || '(no sell)'} · ${c.trade.pnlPct === null ? 'open at end' : `closed ${c.trade.pnlPct}% by ${c.trade.exit}`}` : '';
+            L.push(`    ${short} ${String(c.peakX).padStart(6)}x  window rows ${String(c.windowRows).padStart(3)}  ${why}${tr}`);
+        }
+    }
+    return L.join('\n');
+}

package/dist/packages/autotrade/src/basis-text.js

@@ -0,0 +1,32 @@
+// task-1537: the price basis in autotrade text (the runner's lines, the agents' DOSSIER / ENGINE notes, the ledger's
+// fill JSON). Market cap by default, from the tick's own cap and price (the supply that source counts) or pump.fun's
+// fixed 1B; no supply → the price and why. Display and wording only: the engine, exits and caps read prices.
+import { DEFAULT_PRICE_BASIS, fmtCap, fmtUsdPrice, fmtX, knownSupply, withMcap } from '../../data/src/basis.js';
+export { DEFAULT_PRICE_BASIS };
+/** The supply hints one tick carries (the resolved cap when the task-1518 split rule picked one). */
+export function tickHints(k) {
+    if (!k)
+        return {};
+    return { mint: k.mint, launchpad: k.launchpad, price: k.price, mcap: k.mcapResolved ?? k.mcap, via: 'tick' };
+}
+/** A level in the basis: `$69.7K mcap` / a raw price (price basis, unchanged) / `0.0000697 (price; supply unknown)`. */
+export function levelText(basis, price, k) {
+    if (price === null || price === undefined || !Number.isFinite(price))
+        return '—';
+    if (basis !== 'mcap')
+        return String(price);
+    const sup = knownSupply(tickHints(k));
+    return sup ? `${fmtCap(price * sup.tokens)} mcap` : `${fmtUsdPrice(price)} (price; supply unknown)`;
+}
+/** A row of levels (history, ticks) in the basis: caps at the current supply, else raw prices. */
+export function levelsText(basis, prices, k) {
+    const sup = basis === 'mcap' ? knownSupply(tickHints(k)) : null;
+    return prices.map((p) => (p === null || !Number.isFinite(p) ? '—' : sup ? fmtCap(p * sup.tokens) : String(p))).join(' ');
+}
+/** `x` multiple of the current level over the entry (same in either basis). */
+export function multipleText(entry, now) { return fmtX(entry, now) ?? '—'; }
+/** The ledger's fill JSON keeps BOTH: `price` / `avgPrice` and their caps `mcap` / `avgMcap` (null without a supply). */
+export function fillMcaps(view, k) {
+    const h = tickHints(k);
+    return withMcap(view, { price: 'mcap', avgPrice: 'avgMcap' }, { mint: h.mint, launchpad: h.launchpad, mcap: h.mcap, price: h.price });
+}