dexterm-cli 0.1.7 → 0.2.0

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

@@ -0,0 +1,196 @@
+// dexterm autotrade — the LIVE TRADE FIRE signal, `dexterm-trade-fire/1` (task-1645, 0.2.0 card A).
+//
+// A strategy in mode "real" trades exactly like paper (same clamp, exits, monitor and ledger: the paper fill model is
+// the monitor's own view), and every buy or sell it fills also becomes one of these signals for the user's OWN
+// executor (a Telegram trading bot of their choice, or any script). dexterm holds no key, signs no transaction and
+// builds none: a signal is a request the executor may act on, ignore, or reject.
+//
+//   type "trade"    side buy|sell, mint, sanitized symbol, size in SOL / USD / % of book (a sell also as the fraction
+//                   of the position), price + mcap + liquidity context, exit reason for a sell, strategy id/version/
+//                   hash, run id, account id, nonce, idempotency key, issued/expires, `paper: false`
+//   type "halted"   the run stopped (end, halt, kill, a lost runner): every outstanding signal's nonce, a reason, and
+//                   `open`: the mints dexterm still counts as held for the account (the next real run of the
+//                   strategy takes them over and keeps their exits; they still count against the open-position cap)
+//   type "test"     `dexterm autotrade signal test`: proves the channel; an executor must never trade on it
+//
+// Rules an executor follows (and SignalReceiver below implements, for scripts and the tests' fake executors):
+//   1. verify the HMAC header when a secret is set (`x-dexterm-signature: t=<unix s>,v1=<hex>` over "<t>.<body>")
+//   2. ignore anything past `expiresAt` (the TTL): a late signal is never acted on
+//   3. dedupe by nonce (and the idempotency key `id`): delivery is at-least-once, so a repeat is normal
+//   4. act only on the account id it was set up for
+//
+// Firewall: nothing token-authored rides along except the symbol, reduced to [A-Za-z0-9._$-] (16 chars). No name,
+// no description, no links, no agent text, no paths, no keys. Every other field is an engine number or an id that
+// dexterm validated itself.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+export const TRADE_FIRE_SCHEMA = 'dexterm-trade-fire/1';
+export const SIGNAL_TTL_DEFAULT_SEC = 60;
+export const SIGNAL_TTL_MIN_SEC = 10;
+export const SIGNAL_TTL_MAX_SEC = 600;
+/** How far a signature's timestamp may sit from the receiver's clock. */
+export const SIGNATURE_TOLERANCE_SEC = 300;
+const SOL_MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const ACCOUNT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const RUN_RE = /^[A-Za-z0-9._:-]{1,96}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+/** The only token text a signal carries: NFKC, then [A-Za-z0-9._$-] only, 16 chars, '?' when nothing is left. */
+export function sanitizeSymbol(s) {
+    const t = String(s ?? '').normalize('NFKC').replace(/[^A-Za-z0-9._$-]/g, '').slice(0, 16);
+    return t || '?';
+}
+/** An engine reason ("hard-stop", "time_review:no-answer") reduced to [a-z0-9:_-], 40 chars. */
+export function sanitizeReason(s) {
+    return String(s ?? '').toLowerCase().replace(/[^a-z0-9:_-]/g, '-').replace(/-+/g, '-').slice(0, 40) || 'unknown';
+}
+export const signalIdOf = (accountId, runId, nonce) => createHash('sha256').update(`${TRADE_FIRE_SCHEMA}|${accountId}|${runId}|${nonce}`).digest('hex').slice(0, 32);
+export const clampTtl = (sec) => Math.min(SIGNAL_TTL_MAX_SEC, Math.max(SIGNAL_TTL_MIN_SEC, Math.round(Number.isFinite(sec) ? sec : SIGNAL_TTL_DEFAULT_SEC)));
+const r6 = (v) => Math.round(v * 1e6) / 1e6;
+const r2 = (v) => Math.round(v * 100) / 100;
+const fin = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+function base(type, h) {
+    const ttlSec = clampTtl(h.ttlSec);
+    return {
+        schema: TRADE_FIRE_SCHEMA, type, id: signalIdOf(h.accountId, h.runId, h.nonce), nonce: h.nonce, issuedAt: h.now, expiresAt: h.now + ttlSec * 1000, ttlSec,
+        runId: h.runId, accountId: h.accountId, strategy: { id: h.strategy.id, version: h.strategy.version, hash: h.strategy.hash.slice(0, 64) }, paper: false,
+    };
+}
+/** A trade signal; throws on anything that is not a plain engine value (fail closed: no signal rather than a bad one). */
+export function buildTradeSignal(t, h) {
+    if (!SOL_MINT_RE.test(t.mint))
+        throw new Error('signal: mint is not a base58 address');
+    if (!(t.solUsd > 0))
+        throw new Error('signal: no SOL/USD price');
+    // A buy states a positive size; a sell's size is the modelled proceeds and can be ~0 (a rug exit must still go out).
+    if (t.side === 'buy' ? !(t.sizeUsd > 0) : !(t.sizeUsd >= 0))
+        throw new Error('signal: size must be positive');
+    const s = {
+        ...base('trade', h), type: 'trade', side: t.side, mint: t.mint, symbol: sanitizeSymbol(t.symbol),
+        sizeSol: r6(t.sizeUsd / t.solUsd), sizeUsd: r2(t.sizeUsd), pctOfBook: t.bookUsd > 0 ? Math.round((t.sizeUsd / t.bookUsd) * 1000) / 10 : 0,
+        sellFraction: t.side === 'sell' ? Math.min(1, Math.max(0, r6(t.sellFraction ?? 1))) : null,
+        price: { usd: fin(t.priceUsd), mcap: fin(t.mcap), liqUsd: fin(t.liqUsd), solUsd: r2(t.solUsd) },
+        exitReason: t.side === 'sell' ? sanitizeReason(t.exitReason) : null,
+        slippageBps: Math.round(t.slippageBps), maxImpactPct: t.maxImpactPct, positionId: t.positionId && /^[A-Za-z0-9._-]{1,48}$/.test(t.positionId) ? t.positionId : null,
+        ...(t.model ? { model: { priceUsd: fin(t.model.priceUsd), tokens: fin(t.model.tokens) } } : {}),
+    };
+    const v = validateSignal(s);
+    if (!v.ok)
+        throw new Error(`signal: ${v.error}`);
+    return s;
+}
+export function buildHaltedSignal(reason, outstanding, h, open = []) {
+    return { ...base('halted', h), type: 'halted', reason: sanitizeReason(reason), outstanding: [...new Set(outstanding)].filter((n) => Number.isInteger(n) && n > 0).sort((a, b) => a - b).slice(0, 500), open: [...new Set(open)].filter((m) => SOL_MINT_RE.test(m)).sort().slice(0, 100) };
+}
+export function buildTestSignal(h) {
+    return { ...base('test', h), type: 'test', test: true, note: 'channel test: never trade on this' };
+}
+/** One line of JSON, fixed key order (the webhook body, the hook's stdin, the stream line: byte-identical). */
+export const signalLine = (s) => JSON.stringify(s);
+/** Strict shape check: used on replay of the outbox and by receivers. */
+export function validateSignal(x) {
+    const s = x;
+    if (!s || typeof s !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (s.schema !== TRADE_FIRE_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (s.type !== 'trade' && s.type !== 'halted' && s.type !== 'test')
+        return { ok: false, error: 'type' };
+    if (!Number.isSafeInteger(s.nonce) || s.nonce < 1)
+        return { ok: false, error: 'nonce' };
+    if (typeof s.id !== 'string' || !HEX32.test(s.id))
+        return { ok: false, error: 'id' };
+    if (typeof s.accountId !== 'string' || !ACCOUNT_ID_RE.test(s.accountId))
+        return { ok: false, error: 'accountId' };
+    if (typeof s.runId !== 'string' || !RUN_RE.test(s.runId))
+        return { ok: false, error: 'runId' };
+    if (s.id !== signalIdOf(s.accountId, s.runId, s.nonce))
+        return { ok: false, error: 'id does not match account/run/nonce' };
+    if (s.paper !== false)
+        return { ok: false, error: 'paper must be false' };
+    if (!fin(s.issuedAt) || !fin(s.expiresAt) || s.expiresAt <= s.issuedAt)
+        return { ok: false, error: 'times' };
+    const st = s.strategy;
+    if (!st || typeof st.id !== 'string' || !ID_RE.test(st.id) || typeof st.version !== 'string' || typeof st.hash !== 'string')
+        return { ok: false, error: 'strategy' };
+    if (s.type === 'trade') {
+        if (s.side !== 'buy' && s.side !== 'sell')
+            return { ok: false, error: 'side' };
+        if (typeof s.mint !== 'string' || !SOL_MINT_RE.test(s.mint))
+            return { ok: false, error: 'mint' };
+        if (typeof s.symbol !== 'string' || s.symbol !== sanitizeSymbol(s.symbol))
+            return { ok: false, error: 'symbol' };
+        if (s.side === 'buy' ? !(fin(s.sizeSol) > 0) || !(fin(s.sizeUsd) > 0) : !(fin(s.sizeSol) >= 0) || !(fin(s.sizeUsd) >= 0))
+            return { ok: false, error: 'size' };
+        if (s.side === 'sell' && !(fin(s.sellFraction) > 0 && s.sellFraction <= 1))
+            return { ok: false, error: 'sellFraction' };
+    }
+    if (s.type === 'test' && s.test !== undefined && s.test !== true)
+        return { ok: false, error: 'test' };
+    if (s.type === 'test' && 'mint' in s)
+        return { ok: false, error: 'a test signal names no mint' };
+    if (s.type === 'trade' && s.model !== undefined && (typeof s.model !== 'object' || s.model === null))
+        return { ok: false, error: 'model' };
+    if (s.type === 'halted' && s.open !== undefined && (!Array.isArray(s.open) || s.open.length > 100 || !s.open.every((m) => typeof m === 'string' && SOL_MINT_RE.test(m))))
+        return { ok: false, error: 'open' };
+    return { ok: true, signal: s };
+}
+// ───────────────────────────── HMAC ─────────────────────────────
+/** `t=<unix s>,v1=<hex sha256 hmac of "<t>.<body>">`. */
+export function signBody(secret, body, nowMs) {
+    const t = Math.floor(nowMs / 1000);
+    return `t=${t},v1=${createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')}`;
+}
+export function verifyBody(secret, header, body, nowMs, toleranceSec = SIGNATURE_TOLERANCE_SEC) {
+    const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/.exec(String(header ?? ''));
+    if (!m)
+        return { ok: false, why: 'signature-missing' };
+    const t = Number(m[1]);
+    if (Math.abs(nowMs / 1000 - t) > toleranceSec)
+        return { ok: false, why: 'signature-stale' };
+    const want = createHmac('sha256', secret).update(`${t}.${body}`).digest();
+    const got = Buffer.from(m[2], 'hex');
+    return got.length === want.length && timingSafeEqual(got, want) ? { ok: true } : { ok: false, why: 'signature-bad' };
+}
+/**
+ * What a well-behaved executor does with an incoming signal: signature (when a secret is set), shape, account, TTL,
+ * replay (nonce and id). A duplicate is reported as such so a transport can ack it (at-least-once delivery).
+ * Exported for users' scripts and for the fake executors of the tests; dexterm itself never executes anything.
+ */
+export class SignalReceiver {
+    seen = new Set();
+    maxNonce = 0;
+    o;
+    constructor(o) { this.o = o; }
+    receive(body, signature) {
+        const now = (this.o.now ?? Date.now)();
+        if (this.o.secret) {
+            const v = verifyBody(this.o.secret, signature, body, now);
+            if (!v.ok)
+                return { ok: false, why: v.why };
+        }
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            return { ok: false, why: 'not-json' };
+        }
+        const v = validateSignal(raw);
+        if (!v.ok)
+            return { ok: false, why: `invalid:${v.error}` };
+        const s = v.signal;
+        if (s.accountId !== this.o.accountId)
+            return { ok: false, why: 'wrong-account', signal: s };
+        if (this.seen.has(s.id) || this.seen.has(`n${s.nonce}`))
+            return { ok: false, why: 'duplicate', signal: s };
+        if (now > s.expiresAt)
+            return { ok: false, why: 'expired', signal: s };
+        // A nonce at or below one already acted on (that is not a duplicate of it) is a replay of an old signal.
+        if (s.nonce <= this.maxNonce && s.type !== 'halted')
+            return { ok: false, why: 'nonce-replay', signal: s };
+        this.seen.add(s.id);
+        this.seen.add(`n${s.nonce}`);
+        this.maxNonce = Math.max(this.maxNonce, s.nonce);
+        return { ok: true, signal: s };
+    }
+}

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

@@ -59,7 +59,7 @@ export const SCHEMAS = {
         kind: { type: 'string', enum: ['strategy'] },
         schema: { type: 'string', enum: [STRATEGY_SCHEMA] },
         id: str(32, ID), name: str(40), version: str(16, SEMVER), description: str(600),
-        mode: { type: 'string', enum: ['paper', 'live'] },
+        mode: { type: 'string', enum: ['paper', 'real', 'live'] },
         highRisk: { type: 'boolean' },
         bankroll: obj({ startUsd: num(1, 1e7), source: { type: 'string', enum: ['fixed', 'desk'] } }, ['startUsd']),
         entry: obj({
@@ -213,6 +213,8 @@ export function validateStrategy(doc, library = builtinProfiles()) {
         warnings.push({ path: '/bankroll/source', msg: 'desk reads the paper desk book during a run; backtests use startUsd' });
     if (s.entry.safety.larp)
         warnings.push({ path: '/entry/safety/larp', msg: 'the LARP gate needs the live web (live data runs only); replays and backtests do not evaluate it' });
+    if (s.mode === 'real')
+        warnings.push({ path: '/mode', msg: 'mode real sends a LIVE TRADE FIRE signal for every trade to your own executor; it runs only after `dexterm autotrade signal arm` on your own terminal, at this exact version' });
     if (s.mode === 'live')
         warnings.push({ path: '/mode', msg: 'mode live does not run: dexterm runs strategies on paper only (it holds no key and places no live order); live trading happens in the Telegram trading bot of your choice' });
     if (errors.length)

package/dist/packages/autotrade/src/trade-ledger.js

@@ -9,7 +9,7 @@
 //
 // Where each ledger field comes from:
 //   strategy           run_start: strategy id, version and strategyHash
-//   wallet mode        run_start.mode (paper; a live run's executor name says devnet or mainnet)
+//   wallet mode        run_start.mode (paper; real = a real-mode run, task-1655; a live run's executor name says devnet or mainnet)
 //   profile            the entry fill's profile; 'structured' when the agent's DECISION named it, else 'default'
 //                      (the strategy's default profile), 'rule' for a mechanical (auto) entry
 //   entry reason       the agent's DECISION {"action":"enter","reason":…} of the session that entered (structured)
@@ -70,7 +70,7 @@ export function importRunLedger(path, runId) {
     const start = events.find((e) => e.kind === 'run_start') ?? null;
     const strategy = start && str(start.strategy) ? { id: String(start.strategy), version: str(start.version), hash: str(start.strategyHash) } : null;
     const executor = String(start?.executor ?? '');
-    const walletMode = start?.mode === 'live' ? (/mainnet/.test(executor) ? 'live' : 'devnet') : 'paper';
+    const walletMode = start?.mode === 'real' ? 'real' : start?.mode === 'live' ? (/mainnet/.test(executor) ? 'live' : 'devnet') : 'paper';
     const auto = start?.decide === 'auto';
     // task-1538: a parallel-run strategy on a shared paper account names it in its first line (and run_start).
     const memberLine = events.find((e) => e.kind === 'fleet_member') ?? null;

package/dist/packages/cli/src/analyst/backend.js

@@ -14,7 +14,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ACTION_FILE_ENV, ACTION_TOKEN_ENV, ANALYST_ACTION_TYPES, parseActionLine } from '../../../data/src/index.js';
 import { basisLanguage, DEFAULT_PRICE_BASIS, fmtCap, isPriceBasis, knownSupply, NO_SUPPLY_REASON, pickBasis } from '../../../data/src/basis.js';
-import { firewall, userSkillPreamble, PARALLEL_CONTROL_TOOLS, STRATEGY_PROPOSE_TOOLS } from '../../../mcp/src/index.js';
+import { firewall, userSkillPreamble, JOURNEY_CONTROL_TOOLS, JOURNEY_PROPOSE_TOOLS, PARALLEL_CONTROL_TOOLS, STRATEGY_PROPOSE_TOOLS } from '../../../mcp/src/index.js';
 import { skillStore } from "../kb-skill-cmd.js";
 import { applyCodexEvent, buildCodexArgv, codexAllowedTools, codexDeveloperInstructions, codexFailure, expandSkillPrompt, newCodexTurn, strictSchema } from "./codex.js";
 import { runOllamaTurn } from "./ollama.js";
@@ -37,7 +37,8 @@ export function deniedActionTools(actionTypes) {
         return [];
     // task-1507: an observe-only session (AI scan) cannot propose a strategy edit either
     // task-1529: nor start or stop a parallel strategy
-    const propose = actionTypes.length === 0 ? [...STRATEGY_PROPOSE_TOOLS, ...PARALLEL_CONTROL_TOOLS] : [];
+    // task-1647: nor start / stop a forward test or propose a promotion
+    const propose = actionTypes.length === 0 ? [...STRATEGY_PROPOSE_TOOLS, ...PARALLEL_CONTROL_TOOLS, ...JOURNEY_CONTROL_TOOLS, ...JOURNEY_PROPOSE_TOOLS] : [];
     return [...ANALYST_ACTION_TYPES.filter((t) => !actionTypes.includes(t)), ...propose].map((t) => `mcp__dexterm__${t}`);
 }
 /**

package/dist/packages/cli/src/analyst/codex.js

@@ -17,7 +17,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ACTION_FILE_ENV, ACTION_TOKEN_ENV, ANALYST_ACTION_TYPES } from '../../../data/src/index.js';
-import { READ_ONLY_TOOLS, STRATEGY_PROPOSE_TOOLS } from '../../../mcp/src/index.js';
+import { JOURNEY_PROPOSE_TOOLS, READ_ONLY_TOOLS, STRATEGY_PROPOSE_TOOLS } from '../../../mcp/src/index.js';
 import { skillStore } from "../kb-skill-cmd.js";
 /** The analyst engines dexterm can drive: the user's own claude or codex CLI, or (task-1543) a local model on their Ollama. */
 export const ANALYST_ENGINES = ['claude', 'codex', 'ollama'];
@@ -75,7 +75,8 @@ export function codexAllowedTools(actionTypes) {
     const reads = READ_ONLY_TOOLS.filter((n) => !/^paper_/.test(n) && !ANALYST_ACTION_TYPES.includes(n));
     const actions = ANALYST_ACTION_TYPES.filter((t) => !actionTypes || actionTypes.includes(t));
     // task-1507: strategy PROPOSALS (never applied by a tool) for a chat turn; an observe-only scan gets none
-    const propose = actionTypes && actionTypes.length === 0 ? [] : STRATEGY_PROPOSE_TOOLS;
+    // task-1647: promotion PROPOSALS too (a file the user applies); forward-test control stays off codex, like parallel control
+    const propose = actionTypes && actionTypes.length === 0 ? [] : [...STRATEGY_PROPOSE_TOOLS, ...JOURNEY_PROPOSE_TOOLS];
     return [...reads, ...actions, ...propose];
 }
 const tomlString = (s) => JSON.stringify(s); // a JSON string is a valid TOML basic string

package/dist/packages/cli/src/app-help-gen.js

@@ -232,7 +232,7 @@ const TOPICS = [
         body: '`dexterm autotrade run <id|file> --paper` runs one strategy on paper, headless, one runner per machine: the screener feeds it the same live data as the app (every 10 s, candidate and held coins every 5 s), and each coin that matches gets one session on your own Claude login with the full picture first, then only what changed. Your agent answers with a typed decision (enter, wait, skip, hold, exit, tighten, reprofile); every size is clamped by your strategy and the exits run on their own. At most 2 sessions at once, $0.50 per session and the day caps in ~/.dexterm/autotrade/runner.json (which Claude account, sessions and spend per day, a usage guard). Every step goes to ~/.dexterm/autotrade/runs/<run>.jsonl, hash-chained. `--replay FILE` paces a recorded tape instead of live data; `--stub` uses a scripted agent with no Claude cost. Paper only: a run never signs or touches a wallet, and there is no `--live` (dexterm holds no key and places no live order). Not financial advice. Full docs: https://dexterm.xyz/docs/autotrade/#the-runner-and-candidate-sessions' },
     { id: 'live-trading', title: 'Live trading: dexterm holds no key; a Telegram trading bot of your choice trades', screen: 'all', tags: ['live', 'trading', 'real', 'money', 'telegram', 'bot', 'key', 'wallet', 'custody', 'signer', 'mainnet'],
         commands: ['telegram', 'wallet', 'live'], feature: 'live-trading',
-        body: 'dexterm never holds a key and never signs or sends a transaction: there is no trading wallet, no signer and no live order in dexterm. Live trading happens in a Telegram trading bot of your choice, which holds its own wallet; you act in that bot. dexterm\'s part is the Telegram connector to your OWN bot (`dexterm telegram setup`): alerts, signals and run control for your paper runs. dexterm 0.1.7 does not place orders in a trading bot for you. Paper trading (the ticket, paper accounts, paper autotrade) is local. `dexterm wallet link` keeps a Phantom public key for display only. Not financial advice. Full docs: https://dexterm.xyz/docs/live-trading/' },
+        body: 'dexterm never holds a key and never signs or sends a transaction: there is no trading wallet, no signer and no live order in dexterm. Live trading happens in a Telegram trading bot of your choice, which holds its own wallet; you act in that bot. dexterm\'s part is the Telegram connector to your OWN bot (`dexterm telegram setup`): alerts, signals and run control for your paper runs. dexterm does not place orders in a trading bot for you: in real mode (0.2.0, experimental) a strategy you armed on your own terminal sends a signal for each trade to an executor you run, and your executor places the order by its own rules (`dexterm autotrade signal`, https://dexterm.xyz/docs/real-mode/). Paper trading (the ticket, paper accounts, paper autotrade) is local. `dexterm wallet link` keeps a Phantom public key for display only. Not financial advice. Full docs: https://dexterm.xyz/docs/live-trading/' },
     { id: 'live-yolo', title: 'The full-port yolo strategy on paper: replay and a paper run (HIGH RISK)', screen: 'all', tags: ['yolo', 'full', 'port', 'all-in', 'high', 'risk', 'preset', 'replay', 'paper'],
         commands: ['autotrade'], feature: 'yolo-preset',
         body: 'HIGH RISK, PAPER only; not financial advice. The `yolo` preset enters one young pair at a time on an early 5-minute push after the holder-safety gates (LP burned or locked, no mint or freeze authority, a LARP score of 49 or less checked live before a coin becomes a candidate, liquidity of $25K or more), takes the cost back at about 2x, lets the rest ride on a loose 50% trail, exits at once on a liquidity pull, a dev sell or dead volume, has a -50% stop and a 45-minute time stop, and never buys the same coin twice. On paper it caps an entry at 25% like every strategy. `dexterm autotrade yolo-replay yolo` measures every entry at full port over your recorded history (rugs, the loss spread, how often it zeroed the wallet); `dexterm autotrade run yolo --paper` runs it on paper (`--replay builtin:yolo-rehearsal --stub` for a short fixture run; next to other strategies, or on a shared paper account, through `autotrade.json` and `dexterm autotrade run --all --paper`). Stop: `dexterm autotrade stop`, /kill in Telegram, Ctrl-C. dexterm places no live order. Full docs: https://dexterm.xyz/docs/yolo/' },
@@ -245,13 +245,25 @@ const TOPICS = [
     { id: 'autotrade-telegram', title: 'Your own Telegram bot for the autotrade runner: notify, control, one-tap approvals (dexterm telegram)', screen: 'all', tags: ['telegram', 'bot', 'phone', 'mobile', 'notify', 'notifications', 'approve', 'approval', 'approvals', 'pair', 'pairing', 'kill', 'pause', 'remote', 'botfather'],
         commands: ['telegram'], feature: 'autotrade-telegram',
         body: 'Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/' },
+    { id: 'autotrade-real-signal', title: 'Real mode: send a strategy\'s trades to your own executor as LIVE TRADE FIRE signals (dexterm autotrade signal)', screen: 'all', tags: ['real', 'mode', 'live', 'trade', 'fire', 'signal', 'signals', 'executor', 'webhook', 'hook', 'jsonl', 'receipt', 'receipts', 'arm', 'caps', 'kill', 'outbox', 'nonce'],
+        commands: ['autotrade'], tools: ['trade_fire_feed'], feature: 'autotrade-real-signal',
+        body: 'Real mode runs a strategy exactly like paper (the same clamp, exits, monitor and run file) and sends every buy and sell it fills, first, as a LIVE TRADE FIRE signal (`dexterm-trade-fire/1`: buy or sell, mint, symbol, size in SOL and % of book, the sell fraction and exit reason, strategy, run, account, an always-growing nonce, an idempotency id and an expiry) to YOUR executor: a Telegram trading bot of your choice or any script. dexterm holds no key and signs nothing. Set channels with `dexterm autotrade signal channels --webhook URL | --signal-cmd \'["/abs/path"]\' | --jsonl on | --mcp on | --telegram on` (they live in connectors.json next to the Telegram setup; a bot cannot read another bot, so the Telegram copy alone is not enough), a webhook HMAC secret with `signal secret generate --out FILE`, hard caps with `signal caps set` (raising needs a typed confirmation), then arm on your own terminal with `dexterm autotrade signal arm <id>` (evidence panel + a typed phrase with a one-time code; any later edit disarms; below the evidence floor, a completed forward test with your `minForwardTrades` closed paper trades and a backtest of these exact rules, or past a missing rung of the ladder, it refuses unless you first type a separate OVERRIDE phrase, which is journaled) and run `dexterm autotrade run <id> --real` (live data only, in the foreground: in 0.2.0 the always-on service runs paper strategies only). Delivery is at least once from a restart-safe outbox, in nonce order, retried until acked or expired; the executor dedupes by nonce, ignores expired signals and acts only on its own account. Every run ends with a `halted` signal that lists the positions still open; the run\'s last lines and the Telegram copy name them too. Open positions are carried to the next real run of the same strategy and account, whose exits keep firing; while no real run is running NO signal goes out, sells included, so manage them in your executor. Positions stay unconfirmed until `dexterm autotrade receipt <nonce> executed|rejected|failed` (data only). `signal kill` stops every signal; `signal status`, `signal tail`, `receipt list` and `autotrade audit` show the outbox, receipts and drift; agents can read the MCP feed with trade_fire_feed. No model, tool or chat tap can arm real mode, raise a cap or lift the kill switch. Experimental; not financial advice.' },
+    { id: 'autotrade-limits', title: 'Set your own real-mode limits: per trade, per day, open positions, loss stops, the breaker (dexterm autotrade limits)', screen: 'all', tags: ['limits', 'limit', 'caps', 'cap', 'size', 'sizing', 'per', 'trade', 'daily', 'loss', 'drawdown', 'breaker', 'streak', 'exposure', 'slippage', 'ttl', 'rate', 'raise', 'lower', 'scope'],
+        commands: ['autotrade'], tools: ['trading_limits', 'limits_propose'], feature: 'autotrade-limits',
+        body: 'Every limit real mode enforces is yours to set, in one file (`~/.dexterm/autotrade/real/limits.json`, schema `dexterm-limits/1`): per trade as SOL or as % of the book (the smaller wins), SOL and buys per day, open positions, exposure, min and max position, per coin per day, a daily loss stop, a drawdown breaker, a loss-streak pause, max hold time, the evidence floor for arming (`minForwardTrades`: closed paper trades in a completed forward test, placeholder 10), min liquidity and market cap, max slippage and price impact, the signal TTL, a buy rate limit, an optional sell rate (sells are never capped unless you set one) and how long a silent executor may stay silent. `dexterm autotrade limits show [--strategy ID] [--account ID]` lists what is in force and where each number comes from; `limits set perTradeSol=0.5 dailyLossSol=0.3` (or `--scope real|paper|strategy:ID|account:ID`) changes them: a global number replaces the placeholder default, every other scope can only tighten, and the stricter always wins. Paper runs ignore them unless you add a `paper` scope; then a single paper run (not `run --all`) obeys them on its own state (a replay then needs `--sol-usd N`). Daily counters cover the whole home (every strategy and account), so a strategy or account number can only stop buys sooner. Lowering is immediate, even for a running real run; raising shows the old -> new diff and needs the typed phrase on your own terminal, and applies from the next run. `limits diff`, `limits accept` (a hand-edited file), `limits reset`, `limits breaker reset` (typed) and `limits explain` do the rest. The defaults (0.25 SOL a trade, 1 SOL a day, 20 buys, 3 open, stop at -0.5 SOL a day) are placeholders: arming asks for your own numbers first. The analyst can read and explain them (`trading_limits`) and propose a change as a diff card (`limits_propose`); it can never apply one.' },
+    { id: 'autotrade-executor-kit', title: 'Wire up a test executor, check it is alive, and get the digest (dexterm autotrade executor, signal test, report)', screen: 'all', tags: ['executor', 'kit', 'example', 'heartbeat', 'alive', 'silent', 'health', 'test', 'webhook', 'receiver', 'dry', 'run', 'digest', 'report', 'daily', 'weekly', 'divergence', 'slippage', 'latency'],
+        commands: ['autotrade'], feature: 'autotrade-executor-kit',
+        body: '`dexterm autotrade executor kit --out ~/my-executor` copies the reference executors: a webhook receiver, a `--signal-cmd` hook and a JSONL tail. Each verifies the HMAC, dedupes by nonce, honours the TTL, writes a receipt and a heartbeat, and is DRY RUN: it only logs what it would do, with no wallet code in it. Start one, point a channel at it (`dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal`), then `dexterm autotrade signal test` sends a test signal (`test: true`, no coin, nothing to trade) and shows, per channel, whether it was delivered, how long it took and the executor\'s receipt. `dexterm autotrade executor status` shows the last heartbeat, the last receipt and the lag; a real run pauses new buy signals (exits still go out) when nothing is heard for longer than your `executorSilenceMin` limit, and tells you. With receipts that carry fills, `signal status`, `autotrade audit` and `dexterm autotrade report` show paper vs real: slippage against dexterm\'s own paper fill, latency, partial fills and rejections. `report [--period day|week] [--telegram]` is the digest per strategy and mode with the win rate\'s interval and a small-sample note; `report --schedule daily|weekly` makes a run with your bot on send it.' },
     { id: 'autotrade-chat', title: 'Change an autotrade strategy by chat (paper)', screen: 'autotrade', tags: ['autotrade', 'strategy', 'chat', 'analyst', 'proposal', 'tune', 'change', 'diff', 'looser', 'less', 'safe'],
         actions: [{ action: 'analyst.toggle' }, { action: 'autotrade.proposal', screen: 'autotrade' }],
         tools: ['strategy_list', 'strategy_get', 'strategy_validate', 'strategy_propose_edit', 'strategy_propose_new', 'strategy_backtest', 'autotrade_status'], feature: 'autotrade-chat',
         body: 'Ask the analyst to change one of your strategies ("make my swing exit faster"). It can only PROPOSE: the change arrives as a card on the AUTOTRADE screen (`Q`) with the field lines that change, the validation result and TIGHTER, NEUTRAL or LOOSER. `o` opens the card, `y` applies it as a new version (journaled with who proposed it), `n` dismisses it. When any risk number gets less safe (bigger size or exposure, more loss, a stop or safety gate removed) the edit is LOOSER and needs a second `y` on the less-safe popup. The mode, the book, the daily session budget and the exit-liquidity floor are yours only: the analyst cannot change them. It can backtest a proposal next to the current version on your recorded history (up to 14 days, read-only). Paper only.' },
+    { id: 'autotrade-journey', title: 'Build a strategy by chat, back-test it, forward-test it, then promote it (paper, then real)', screen: 'all', tags: ['autotrade', 'strategy', 'build', 'chat', 'journey', 'ladder', 'backtest', 'held-out', 'forward', 'test', 'promote', 'promotion', 'always-on', 'real', 'evidence'],
+        commands: ['autotrade'], tools: ['strategy_journey', 'strategy_forward_start', 'strategy_forward_stop', 'strategy_forward_report', 'strategy_promote_propose'], feature: 'autotrade-journey',
+        body: 'A strategy climbs one ladder, one rung at a time: draft → backtested → forward-tested → always-on (paper) → real. Each rung needs evidence measured on that strategy\'s exact rules; any rule change starts it again (a rename or arming keeps it). Ask the analyst to build one ("build me a strategy that buys young pairs on a 5-minute push and takes profit at 2x"): it proposes a copy of a preset with changes (strategy_propose_new), you apply it on the Q screen. BACKTESTED: `dexterm autotrade backtest <id>` or strategy_backtest runs it on recorded history and on each half of the held-out split (the newest 30% of coins); verdict rule 6 allows gain wording only with at least 20 trades in both halves and a held-out net above 0. FORWARD-TESTED: `dexterm autotrade forward start <id> --hours 24` (or `--trades N`, or strategy_forward_start from the chat) runs the same version on the LIVE tape, on paper, with its own bankroll and run file, in the background next to the always-on service; `forward status`, `forward stop` and `forward report` (the forward numbers next to the backtest: trades, win rate with its interval, net, drawdown, rug rate, fill cost drift, and a plain line when a sample is too small). Only a test that ran its whole window on live data counts. ALWAYS-ON: the analyst can propose it (strategy_promote_propose), you apply it with `dexterm autotrade promote apply <pp-id>` (y on your own terminal) or on the Q screen journey view (`J`, then `y`); it joins autotrade.json and the always-on service runs it on paper. REAL: you set your own limits (`dexterm autotrade limits set`; `signal caps set` sets four of them), then `dexterm autotrade promote <id> --to real` hands over to `signal arm` (evidence panel, typed phrase with a one-time code). No tool or model can apply a promotion, skip a rung, set a cap, pick a bankroll or arm real mode. `dexterm autotrade journey <id>` shows where a strategy stands. Paper by default; not financial advice.' },
     { id: 'trade-ledger', title: 'See every trade in one ledger: win rate, profiles, exit reasons, strategy versions (dexterm ledger)', screen: 'all', tags: ['ledger', 'journal', 'trades', 'history', 'results', 'stats', 'win', 'rate', 'drawdown', 'profile', 'exit', 'reason', 'compare', 'export', 'csv', 'equity', 'mfe', 'mae'],
         commands: ['ledger'], tools: ['ledger_trades', 'ledger_positions', 'ledger_summary', 'ledger_equity', 'ledger_compare', 'candidate_dossier', 'outcomes_lookup', 'trading_status', 'telegram_status', 'backtest_requests'], feature: 'trade-ledger',
-        body: '`dexterm ledger trades` lists every round trip dexterm booked, from the paper ticket, the agent paper desk and autotrade runs, newest first: strategy version, the exit profile and entry reason it was opened with (marked * when not declared with the fill), the exit reason, size and % of book, entry and exit market cap, P/L, hold and MFE/MAE. `positions` shows the open ones. `summary` gives the win rate with its 95% interval, P/L, profit factor, drawdown and rug rate by profile, exit reason, strategy, source and mode; `equity` the realized equity curve; `compare` strategy versions side by side (for strategies run in parallel); `export csv|json|parquet-lite [--out FILE]`; `card <tradeId>` a PnL card from a row. Filters: --source, --mode paper|devnet|live, --strategy id[@version], --profile, --exit, --mint, --run, --days, --status. Reads never write; `dexterm ledger sync` appends to ~/.dexterm/ledger/trades.jsonl (sha256-chained) and `dexterm ledger verify` names the first edited line. Agents read the same rows with the read-only ledger_* tools; `trading_status` and `telegram_status` show settings and state, never a key, address, exact balance, bot token or chat id. A backtest an agent asks for (backtest_request) only runs when you run it: `dexterm autotrade requests`. PAPER rows are simulated; filter by --mode before comparing. Not financial advice. Full docs: https://dexterm.xyz/docs/paper-trading/#the-trade-ledger' },
+        body: '`dexterm ledger trades` lists every round trip dexterm booked, from the paper ticket, the agent paper desk and autotrade runs, newest first: strategy version, the exit profile and entry reason it was opened with (marked * when not declared with the fill), the exit reason, size and % of book, entry and exit market cap, P/L, hold and MFE/MAE. `positions` shows the open ones. `summary` gives the win rate with its 95% interval, P/L, profit factor, drawdown and rug rate by profile, exit reason, strategy, source and mode; `equity` the realized equity curve; `compare` strategy versions side by side (for strategies run in parallel); `export csv|json|parquet-lite [--out FILE]`; `card <tradeId>` a PnL card from a row. Filters: --source, --mode paper|devnet|live|real (real = a real-mode run: dexterm\'s model of the trades it signalled), --strategy id[@version], --profile, --exit, --mint, --run, --days, --status. Reads never write; `dexterm ledger sync` appends to ~/.dexterm/ledger/trades.jsonl (sha256-chained) and `dexterm ledger verify` names the first edited line. Agents read the same rows with the read-only ledger_* tools; `trading_status` and `telegram_status` show settings and state, never a key, address, exact balance, bot token or chat id. A backtest an agent asks for (backtest_request) only runs when you run it: `dexterm autotrade requests`. PAPER rows are simulated; filter by --mode before comparing. Not financial advice. Full docs: https://dexterm.xyz/docs/paper-trading/#the-trade-ledger' },
     { id: 'coin-images', title: 'Turn coin images on or off', screen: 'all', tags: ['images', 'image', 'pictures', 'icons', 'logos', 'off'],
         flags: ['--no-images'], feature: 'coin-images',
         body: 'Coin pictures render as real pixels in image-capable terminals (kitty/iTerm2/sixel) and as block art everywhere else. Turn them off with `--no-images` (or `DEXTERM_IMAGES=0`, or `enabled:false` in `~/.dexterm/images.json`). `dexterm doctor` has a Coin images line that says which path you get.' },

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

@@ -4,7 +4,8 @@
 // hash covers the previous hash and its own content) and checks it against the run's summary, so an edited, added,
 // dropped, reordered or cut-off line is named with its event number. Exit 1 when any checked run is broken.
 import { dextermHome } from '../../../custom/src/index.js';
-import { auditRun, listRunIds } from '../../../autotrade/src/index.js';
+import { existsSync } from 'node:fs';
+import { Outbox, allOutboxSignals, auditRun, divergenceLines, divergenceReport, driftReport, listRunIds, outboxPath, readReceipts } from '../../../autotrade/src/index.js';
 import { parseArgs } from "./strategies.js";
 export const AUDIT_USAGE = 'dexterm autotrade audit [<run-id>|--last] [--verify] [--json]';
 function line(a, verify) {
@@ -38,8 +39,19 @@ export async function auditCmd(argv, io) {
     const verify = !!opts.verify;
     const audits = ids.map((id) => auditRun(home, id));
     const broken = verify ? audits.filter((a) => !a.ok) : [];
+    // task-1645: real mode: the drift between the trade-fire signals and the executor's receipts.
+    let real = null;
+    // task-1654: paper vs real: each receipted fill against dexterm's own paper fill (every outbox file, archives too).
+    let divergence = null;
+    if (existsSync(outboxPath(home))) {
+        const receipts = readReceipts(home).receipts;
+        const { rows: _rows, ...rest } = driftReport(Outbox.open(home, { channels: [], noLock: true }).signals(), receipts, Date.now());
+        real = rest;
+        const { rows: _r2, ...dv } = divergenceReport(allOutboxSignals(home), receipts);
+        divergence = dv;
+    }
     if (opts.json) {
-        io.stdout.write(`${JSON.stringify({ verified: verify, runs: audits, broken: broken.length }, null, 2)}\n`);
+        io.stdout.write(`${JSON.stringify({ verified: verify, runs: audits, broken: broken.length, ...(real ? { realSignals: real } : {}), ...(divergence ? { paperVsReal: divergence } : {}) }, null, 2)}\n`);
         return broken.length ? 1 : 0;
     }
     if (!audits.length) {
@@ -53,5 +65,10 @@ export async function auditCmd(argv, io) {
         io.stdout.write(broken.length ? `${broken.length} broken ledger${broken.length === 1 ? '' : 's'}: the lines from that event on cannot be trusted\n` : 'every chain verifies\n');
     else
         io.stdout.write('add --verify to recompute the hash chains\n');
+    if (real)
+        io.stdout.write(`real-mode signals vs receipts · executed ${real.counts.executed} · rejected ${real.counts.rejected} · failed ${real.counts.failed} · unconfirmed ${real.unconfirmed}${real.sizeDrift ? ` · size drift on ${real.sizeDrift}` : ''}${real.orphanReceipts ? ` · ${real.orphanReceipts} orphan receipt(s)` : ''} (dexterm autotrade receipt list)\n`);
+    if (divergence?.receipted)
+        for (const l of divergenceLines(divergence))
+            io.stdout.write(`${l}\n`);
     return broken.length ? 1 : 0;
 }

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

@@ -1,11 +1,12 @@
 // `dexterm autotrade backtest|sweep|extract` (task-1503 AT-1, AUTOTRADE-SPEC §3/§3a). PAPER, recorded data only:
 // the recorder DB is opened read-only, fills are modelled, no network, no model, no keys. Mechanical entries
 // (`auto`): the agent's judgement is what the runner card measures, so a backtest never spawns a session.
+import { dextermHome } from '../../../custom/src/index.js';
 import { defaultDbPath } from '../../../data/src/index.js';
 import { openHistoryReadOnly } from '../../../recorder/src/index.js';
-import { backtest, everyCandidate, fmtIssue, loadTape, renderRecall, renderReport, renderSweep, renderYoloReplay, builtinTapePath, runnerRecall, saveTape, sweep, tapeFromDb, tapeFromDoc, yoloReplay, } from '../../../autotrade/src/index.js';
+import { backtest, backtestEvidence, everyCandidate, recordBacktestEvidence, renderHeldOut, fmtIssue, loadTape, renderRecall, renderReport, renderSweep, renderYoloReplay, builtinTapePath, runnerRecall, saveTape, sweep, tapeFromDb, tapeFromDoc, yoloReplay, } from '../../../autotrade/src/index.js';
 import { parseArgs, resolveStrategyArg, storeFor } from "./strategies.js";
-const BOOL = ['json', 'every-candidate'];
+const BOOL = ['json', 'every-candidate', 'no-held-out'];
 function strategyFrom(pos, opts, io, usage, anyMode = false) {
     const arg = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
     const r = resolveStrategyArg(arg, io);
@@ -99,7 +100,8 @@ export function tapeFrom(opts, io) {
 }
 export async function backtestCmd(argv, io) {
     const { pos, opts } = parseArgs(argv, BOOL);
-    const usage = 'dexterm autotrade backtest <id|file> [--tape FILE | --db PATH] [--days N | --since T] [--until T] [--every-candidate [--unit-usd 20]] [--recall 5,10] [--json]';
+    const usage = 'dexterm autotrade backtest <id|file> [--tape FILE | --db PATH] [--days N | --since T] [--until T] [--every-candidate [--unit-usd 20]] [--recall 5,10] [--no-held-out] [--json]';
+    const arg = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
     const s0 = strategyFrom(pos, opts, io, usage);
     if (!s0)
         return 2;
@@ -116,11 +118,26 @@ export async function backtestCmd(argv, io) {
         }
         catch { /* the line is a convenience for `list`; never fail a backtest on it */ }
     }
+    // task-1647: a stored strategy's backtest is journey evidence: the same rules on each half of the held-out split.
+    let evidence = null;
+    const stored = !!arg && !opts['every-candidate'] && !opts['no-held-out'] && storeFor(io).get(arg)?.ok === true && arg === s.id;
+    if (stored) {
+        const days = numOpt(opts, 'days', 0);
+        evidence = (await backtestEvidence(s, tape, { by: 'user', days: days > 0 ? days : null, full: { report, run } })).evidence;
+        try {
+            recordBacktestEvidence(dextermHome(io.env), evidence);
+        }
+        catch (e) {
+            io.stderr.write(`warning: the journey record was not written (${e.message})\n`);
+        }
+    }
     if (opts.json) {
-        io.stdout.write(JSON.stringify(recall ? { ...report, recall } : report, null, 2) + '\n');
+        io.stdout.write(JSON.stringify({ ...report, ...(recall ? { recall } : {}), ...(evidence ? { heldOut: evidence.heldOut, evidence: { verdict: evidence.verdict, claim: evidence.claim, rulesHash: evidence.rulesHash } } : {}) }, null, 2) + '\n');
         return 0;
     }
     io.stdout.write(renderReport(report) + '\n');
+    if (evidence)
+        io.stdout.write(renderHeldOut(evidence).join('\n') + `\n  journey: recorded as the backtest of ${s.id} v${s.version} (dexterm autotrade journey ${s.id})\n`);
     if (opts['every-candidate'])
         io.stdout.write(`  every-candidate copy of ${s0.id}: each candidate entered at $${numOpt(opts, 'unit-usd', 20)} with the book caps lifted (an evaluation, not a strategy to run)\n`);
     if (recall)

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

@@ -0,0 +1,91 @@
+// `dexterm autotrade executor …` (task-1654, 0.2.0 card E): is YOUR executor alive?
+//
+//   status     the last heartbeat, the last receipt, the receipt lag, and whether a real run would pause new buys now
+//   heartbeat  append one heartbeat (for executors that prefer to shell out; the kit appends or POSTs its own)
+//   kit        copy the executor reference kit (webhook / signal-cmd / JSONL tail, all dry run) to a folder of yours
+//
+// A heartbeat is data: it can only keep new buy signals from pausing. It cannot raise a limit, lift the kill switch,
+// reset the breaker or confirm a position (receipts do that, and only as data).
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dextermHome } from '../../../custom/src/index.js';
+import { Outbox, appendHeartbeat, effectiveLimits, executorHealth, healthLine, heartbeatPath, loadLimits, readReceipts, ACCOUNT_ID_RE } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+/** The kit inside the app (shipped in the npm package too: build-dist copies examples/). */
+export const KIT_DIR = fileURLToPath(new URL('../../../autotrade/examples/executor/', import.meta.url));
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, s) => { io.stderr.write(`dexterm autotrade executor: ${s}\n`); };
+export async function executorCmd(argv, io, deps = {}) {
+    const home = dextermHome(io.env);
+    const now = deps.now ?? Date.now;
+    const { pos, opts } = parseArgs(argv.slice(1), ['json', 'dry-run']);
+    switch (argv[0]) {
+        case undefined:
+        case 'help':
+            out(io, 'dexterm autotrade executor status [--json] | heartbeat [--name N] [--account ID] [--dry-run] [--nonce N] [--note TEXT] | kit --out DIR');
+            return 0;
+        case 'kit': {
+            if (typeof opts.out !== 'string') {
+                err(io, 'kit --out DIR (a new or empty folder)');
+                return 2;
+            }
+            const dir = resolve(opts.out);
+            if (existsSync(dir) && readdirSync(dir).length) {
+                err(io, `${dir} is not empty`);
+                return 1;
+            }
+            mkdirSync(dir, { recursive: true });
+            const files = readdirSync(KIT_DIR).filter((f) => /\.(mjs|md)$/.test(f));
+            for (const f of files)
+                copyFileSync(join(KIT_DIR, f), join(dir, f));
+            out(io, `executor reference kit (DRY RUN: it logs what it would do; no wallet code) copied to ${dir}: ${files.join(', ')}`);
+            out(io, `  start one:  node ${join(dir, 'webhook-executor.mjs')} --account main`);
+            out(io, '  wire it:    dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal');
+            out(io, '  prove it:   dexterm autotrade signal test   (then dexterm autotrade executor status)');
+            return 0;
+        }
+        case 'status': {
+            const l = loadLimits(home);
+            const e = effectiveLimits(l.ok ? l.doc : null, { strategyId: '-', accountId: '-', mode: 'real' });
+            const ob = Outbox.open(home, { channels: [], noLock: true });
+            const h = executorHealth(home, { now: now(), windowMin: e.values.executorSilenceMin ?? null, signal: (n) => ob.get(n), receipts: readReceipts(home).receipts });
+            if (opts.json) {
+                out(io, JSON.stringify(h, null, 2));
+                return 0;
+            }
+            out(io, `executor  ${healthLine(h)}`);
+            out(io, `  heartbeats: ${heartbeatPath(home)} (append, POST to the run's listener, or dexterm autotrade executor heartbeat)`);
+            if (h.alive === false)
+                out(io, '  a real run would PAUSE new buy signals now (exits still go out); start your executor, then dexterm autotrade signal test');
+            return 0;
+        }
+        case 'heartbeat': {
+            if (pos.length) {
+                err(io, `unexpected ${pos.join(' ')}`);
+                return 2;
+            }
+            const accountId = typeof opts.account === 'string' ? opts.account : null;
+            if (accountId && !ACCOUNT_ID_RE.test(accountId)) {
+                err(io, '--account: lowercase letters, digits, - and _');
+                return 2;
+            }
+            const nonce = opts.nonce === undefined ? null : Number(opts.nonce);
+            try {
+                const hb = appendHeartbeat(home, { at: now(), executor: typeof opts.name === 'string' ? opts.name : 'cli', accountId, dryRun: opts['dry-run'] === true ? true : null, lastNonce: nonce, note: typeof opts.note === 'string' ? opts.note : null });
+                if (opts.json)
+                    out(io, JSON.stringify(hb));
+                else
+                    out(io, `heartbeat from ${hb.executor} recorded`);
+                return 0;
+            }
+            catch (e) {
+                err(io, e.message);
+                return 2;
+            }
+        }
+        default:
+            err(io, `unknown subcommand ${JSON.stringify(argv[0])}`);
+            return 2;
+    }
+}

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

@@ -161,7 +161,7 @@ export async function fleetRunCmd(argv, io, over = {}) {
             continue;
         }
         if (r.strategy.mode !== 'paper') {
-            problems.push(`${m.id}: ${r.strategy.id} is mode "${r.strategy.mode}"; the runner refuses anything but paper`);
+            problems.push(`${m.id}: ${r.strategy.id} is mode "${r.strategy.mode}"; the runner refuses anything but paper${r.strategy.mode === 'real' ? ` in a parallel run (real mode runs one strategy on its own: dexterm autotrade run ${r.strategy.id} --real)` : ''}`);
             continue;
         }
         const acct = m.account ? accountOf.get(m.account) : undefined;
@@ -174,7 +174,8 @@ export async function fleetRunCmd(argv, io, over = {}) {
         }
         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 } });
+        const adopt = over.adopt?.(m.id);
+        members.push({ config: m, strategy, basedOn, bankroll: { usd: strategy.bankroll.startUsd, ...sol }, ...(adopt?.length ? { adopt } : {}) });
     }
     if (problems.length) {
         io.stderr.write(`dexterm autotrade run --all: nothing started:\n${problems.map((p) => `  ${p}`).join('\n')}\n`);
@@ -199,6 +200,7 @@ export async function fleetRunCmd(argv, io, over = {}) {
     clearMemberControls(home, fleetId);
     const { ledger: fleetLedger, files: fleetFiles } = fileLedger(home, fleetId);
     const startedAt = Date.now();
+    over.onStarted?.(fleetId, fleetLedger);
     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
@@ -300,11 +302,13 @@ export async function fleetRunCmd(argv, io, over = {}) {
         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,
+            sessions, dossier, vet: over.vetWrap ? (m) => over.vetWrap(m, vet?.(m)) : vet, newRunId: (id) => newRunId(id), verbose: true, onLine: say,
             globalSafety: () => {
                 if (Date.now() >= stopAt)
                     stop('max-minutes');
-                const v = safety.step();
+                const s0 = safety.step();
+                const extra = over.extraSafety?.().pauseEntries ?? null;
+                const v = extra && !s0.pauseEntries ? { ...s0, pauseEntries: extra } : s0;
                 return stopping && !v.halt ? { ...v, halt: 'runner-stopped', detail: 'a signal or --max-minutes', endWhenFlat: true } : v;
             },
             hooks: {