dexterm-cli 0.1.7 → 0.2.0

package/dist/packages/mcp/assets/kb/docs/docs-real-mode-the-signal.md

@@ -0,0 +1,48 @@
+---
+id: docs-real-mode-the-signal
+title: Real mode (LIVE TRADE FIRE signals) › The signal
+kind: docs
+page: real-mode
+page_title: Real mode (LIVE TRADE FIRE signals)
+heading: The signal
+anchor: the-signal
+url: https://dexterm.xyz/docs/real-mode#the-signal
+tags:
+  - docs
+  - real-mode
+  - signal
+  - real
+  - mode
+  - live
+  - trade
+  - fire
+  - signals
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/real-mode.md
+date: 2026-10-16
+---
+
+One line of JSON, the same bytes on every channel:
+
+```json
+{"schema":"dexterm-trade-fire/1","type":"trade","id":"9f2c…(32 hex)","nonce":42,"issuedAt":1792000000000,"expiresAt":1792000060000,"ttlSec":60,"runId":"…","accountId":"main","strategy":{"id":"my-strategy","version":"1.0.1","hash":"…"},"paper":false,"side":"buy","mint":"…","symbol":"PEPE","sizeSol":0.05,"sizeUsd":10,"pctOfBook":2,"sellFraction":null,"price":{"usd":0.0012,"mcap":1200000,"liqUsd":48000,"solUsd":200},"exitReason":null,"slippageBps":300,"maxImpactPct":3,"positionId":"…"}
+```
+
+- `type`: `trade`, `halted` (the run ended or stopped: `outstanding` lists the nonces it had sent that had not expired, `open` the coins dexterm still counts as held for the account) or `test`.
+- `side` `buy` or `sell`. A buy states `sizeSol` (what to spend) and `pctOfBook`. A sell states `sellFraction`, the share of the position to sell (apply it to what you really hold), and `exitReason` (the exit rule that fired: `hard-stop`, `trail`, `tp-1`, `agent-exit`, `flatten` and so on); its `sizeSol` is dexterm's modelled proceeds and can be 0 for a coin that rugged.
+- `nonce` only ever grows, across runs and restarts. `id` is the idempotency key (a hash of the account, the run and the nonce). `paper` is always `false`.
+- **Firewall**: the only token-made text in a signal is the symbol, reduced to `A-Z a-z 0-9 . _ $ -` (16 characters). No name, no description, no link, no agent text, no path, no key.
+
+**What a well-behaved executor does with each signal:**
+
+1. Check the HMAC (when you set a secret): `x-dexterm-signature: t=<unix seconds>,v1=<hex>`, where `v1` is HMAC-SHA256 of `<t>.<body>` with your secret. Refuse a timestamp more than 5 minutes off.
+2. Ignore it after `expiresAt`. A late signal is never acted on.
+3. Act once per `nonce` (delivery is at least once: a repeat is normal) and ignore a nonce lower than one already acted on.
+4. Act only on the `accountId` it was set up for.
+
+`SignalReceiver` in `@dexterm/autotrade` does these four checks, if your executor is written in Node.

package/dist/packages/mcp/assets/kb/docs/docs-real-mode-what-it-is.md

@@ -0,0 +1,35 @@
+---
+id: docs-real-mode-what-it-is
+title: Real mode (LIVE TRADE FIRE signals) › What it is
+kind: docs
+page: real-mode
+page_title: Real mode (LIVE TRADE FIRE signals)
+heading: What it is
+anchor: what-it-is
+url: https://dexterm.xyz/docs/real-mode#what-it-is
+tags:
+  - docs
+  - real-mode
+  - real
+  - mode
+  - live
+  - trade
+  - fire
+  - signals
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/real-mode.md
+date: 2026-10-16
+---
+
+> **0.2.0, experimental.** Real mode can lead to real trades in a wallet you fund. dexterm never holds a key, never signs and never sends a transaction: your executor does, by its own rules. Not financial advice.
+
+Every strategy runs on **paper** by default. In **real** mode the same strategy runs the same way: the same entry rules, the same clamp on every size, the same exits, the same monitor and the same run file as paper. The difference: every buy and sell it fills on its own model of the market also goes out, first, as a **LIVE TRADE FIRE** signal (`dexterm-trade-fire/1`) to the executor you chose.
+
+- **Your executor** is a Telegram trading bot you trust, or any script of yours. It holds its own wallet and decides whether to act on a signal.
+- **dexterm** holds no key, signs nothing and builds no transaction. It sends the signal, keeps it in an outbox until it is delivered, and records what your executor says it did.
+- **A bot cannot read another bot's messages**, so the signal also goes over a channel your executor can read: a local webhook, a command, a stream file or MCP. The Telegram message to your own chat is the copy for you.

package/dist/packages/mcp/assets/kb/docs/docs-real-mode-what-it-will-not-do.md

@@ -0,0 +1,34 @@
+---
+id: docs-real-mode-what-it-will-not-do
+title: Real mode (LIVE TRADE FIRE signals) › What it will not do
+kind: docs
+page: real-mode
+page_title: Real mode (LIVE TRADE FIRE signals)
+heading: What it will not do
+anchor: what-it-will-not-do
+url: https://dexterm.xyz/docs/real-mode#what-it-will-not-do
+tags:
+  - docs
+  - real-mode
+  - will
+  - real
+  - mode
+  - live
+  - trade
+  - fire
+  - signals
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/real-mode.md
+date: 2026-10-16
+---
+
+- Hold, import or ask for a key or a seed phrase, sign, or send a transaction.
+- Trade on a replay, or let a chat tap authorise a real trade.
+- Promise a fill. Your executor decides, at its own price, with its own fees.
+- Run more than one real strategy per machine at a time, run one inside `run --all`, or run one under the always-on service (in 0.2.0 real runs in the foreground only).
+- Send any signal, sells included, while no real run is running, or close a position by itself.

package/dist/packages/mcp/assets/kb/docs/docs-real-mode-where-you-see-it.md

@@ -0,0 +1,34 @@
+---
+id: docs-real-mode-where-you-see-it
+title: Real mode (LIVE TRADE FIRE signals) › Where you see it
+kind: docs
+page: real-mode
+page_title: Real mode (LIVE TRADE FIRE signals)
+heading: Where you see it
+anchor: where-you-see-it
+url: https://dexterm.xyz/docs/real-mode#where-you-see-it
+tags:
+  - docs
+  - real-mode
+  - where
+  - real
+  - mode
+  - live
+  - trade
+  - fire
+  - signals
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/real-mode.md
+date: 2026-10-16
+---
+
+- **The run**: every fill and closed trade row of a real run is tagged `real-signal` and names its nonce; the start line says REAL; receipts become rows; the end has a `real_halted` row.
+- **The `Q` screen's runner view**: the mode, the account, the kill switch, the outbox depth, each channel's health, the unconfirmed positions, the limits in force (with a BUYS PAUSED line when a limit or a silent executor stops new buys) and your executor's health.
+- **Telegram**: every message of a real run carries the LIVE badge. A closed trade is a text line (its numbers are dexterm's model, not your executor's fills), never a PnL card.
+- **The trade ledger**: `dexterm ledger` lists a real run's trades with the mode `real` (`--mode real`), never `paper`. Their numbers are dexterm's model of each trade it signalled; your executor's receipts are the real fills, so there is no PnL card for them.
+- **Shared views**: the spectator stream and saved files keep signals and receipts out.

package/dist/packages/mcp/assets/kb/docs/docs-real-mode.md

@@ -0,0 +1,27 @@
+---
+id: docs-real-mode
+title: Real mode (LIVE TRADE FIRE signals)
+kind: docs
+page: real-mode
+page_title: Real mode (LIVE TRADE FIRE signals)
+url: https://dexterm.xyz/docs/real-mode
+tags:
+  - docs
+  - real-mode
+  - real
+  - mode
+  - live
+  - trade
+  - fire
+  - signals
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/real-mode.md
+date: 2026-10-16
+---
+
+Run a strategy in real mode and every buy and sell it decides goes to your own executor (a Telegram trading bot of your choice, or any script) as a signed, numbered LIVE TRADE FIRE signal. dexterm still holds no key and signs nothing. Experimental; not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-telegram-what-it-is.md

@@ -30,4 +30,4 @@ It does three things, each one a tier you grant when you pair:
 - **Control** (https://dexterm.xyz/docs/telegram#control-the-commands): `/status`, `/positions`, `/pause`, `/resume`, `/kill`, `/flatten`, `/strategies`, `/use` and `/approvals on`. Chat can always make things **safer** and never less safe.
 - **Approve** (https://dexterm.xyz/docs/telegram#approve-one-tap-entries): every new entry waits for your tap, with [Approve] [Half size] [Skip] buttons. Only a button approves; a typed message never does.
 
-It runs on **paper**: an approved entry fills on the paper book, with no key, wallet or signer anywhere. This is also dexterm's part in live trading (https://dexterm.xyz/docs/live-trading): dexterm holds no key, and live trades happen in a separate Telegram trading bot of your choice, which holds its own wallet. dexterm sends the alerts and run control to your chat; in this version it does not place orders in that trading bot for you. Experimental, not financial advice.
+It runs on **paper**: an approved entry fills on the paper book, with no key, wallet or signer anywhere. This is also dexterm's part in live trading (https://dexterm.xyz/docs/live-trading): dexterm holds no key, and live trades happen in a separate Telegram trading bot of your choice, which holds its own wallet. dexterm sends the alerts and run control to your chat; in this version it does not place orders in that trading bot for you. In real mode (https://dexterm.xyz/docs/real-mode) (coming in 0.2.0) your chat also gets a LIVE TRADE FIRE copy of each signal, and the channels your executor reads are set up in the same file as this bot (`dexterm autotrade signal channels`; `dexterm telegram status` shows them). Experimental, not financial advice.

package/dist/packages/mcp/assets/kb/entries/autotrade.md

@@ -7,7 +7,7 @@ tags:
   - paper
   - backtest
   - proposal
-date: 2026-10-21
+date: 2026-10-24
 confidence: high
 owner: maintainers
 origin: primary-doc
@@ -33,6 +33,8 @@ sources:
 - "stricter coins" → add a screen clause (`top10 <= 25`) or tighten `/entry/safety/*`.
 - "stop after a bad day" → lower `/risk/dailyLossHaltPct` or `/risk/drawdown/haltAtPct`.
 
-**Then measure.** `strategy_backtest {proposalId}` runs the current version and the proposal on the same recorded tape (days <= 14, read-only, rate-limited). Quote the trade count and the data limits: small n means little, fills are modelled, and early-entry rugs are often unsellable. A backtest is never a prediction and never financial advice.
+**Then measure.** `strategy_backtest {proposalId}` runs the current version and the proposal on the same recorded tape (days <= 14, rate-limited; a proposal's backtest saves nothing). `strategy_backtest {id}` also runs the strategy on each half of the held-out split and records it as the strategy's backtest evidence. Quote the trade count and the data limits: small n means little, fills are modelled, and early-entry rugs are often unsellable. A backtest is never a prediction and never financial advice.
 
 **Status.** `autotrade_status` shows the paper runner (heartbeat, halt, candidates, sessions and spend, positions) and the proposals waiting for the user.
+
+**The journey (one rung at a time).** draft → backtested (`strategy_backtest {id}`: held-out split recorded) → forward-tested (`strategy_forward_start {id, hours|trades}`: paper, live data, its own bankroll; read `strategy_forward_report` when it ends; an early stop never counts) → always-on → real (`strategy_promote_propose {id, to}`). `strategy_journey {id}` shows the rungs; evidence binds to the exact rules. Never skip a rung, apply a promotion, set or suggest caps, pick a bankroll or arm anything: say "I proposed it; you apply it". Claim gains only when `heldOut.claim` / `comparison.claim` is true (>= 20 trades in both halves, net above 0); otherwise "too few trades to claim anything".

package/dist/packages/mcp/src/autotrade-tools.js

@@ -10,6 +10,19 @@
 //   strategy_backtest      observe  a strategy or a proposal on recorded history (days <= 14), read-only, rate-limited
 //   autotrade_status       observe  the paper runner's status file, strategies and pending proposals
 //
+// task-1647 (0.2.0 card C), the JOURNEY draft -> backtested -> forward-tested -> always-on -> real:
+//
+//   strategy_journey          observe  the ladder for one strategy: which rungs have evidence on these rules, what is next
+//   strategy_forward_report   observe  a forward test next to the backtest (held-out split) of the same rules
+//   strategy_forward_start    control  start a forward test: live data, paper, the strategy's OWN bankroll, a window
+//                                      (hours <= 72 or closed trades <= 200); only after a backtest; never real
+//   strategy_forward_stop     control  stop one (it flattens and writes its report; an early stop never counts)
+//   strategy_promote_propose  propose  a PROMOTION proposal (always-on or real) with an evidence card, never applied;
+//                                      no rung can be skipped; always-on is the user's y, real is the user's own
+//                                      caps + `signal arm` with a typed phrase on their terminal
+//   strategy_backtest now also runs the strategy on each half of the held-out split and records that as the
+//   strategy's backtest evidence (the engine's numbers on the recorded tape, never model text).
+//
 // A proposal is a file in `$DEXTERM_HOME/strategies/.proposals/`. Nothing in this module writes a strategy:
 // the user applies a proposal on the Q screen with a keypress (a LOOSER one needs a second keypress, the
 // "less safe" popup), and that path re-checks everything here from scratch (`checkProposal`) instead of trusting
@@ -19,8 +32,9 @@
 //
 // @dexterm/autotrade imports @dexterm/mcp (the firewall), so the server loads the engine lazily (`loadEngine`);
 // the CLI hands its own static import to the same functions.
+import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { firewallText } from '../../data/src/index.js';
 import { firewall } from "./firewall.js";
@@ -42,6 +56,21 @@ export const AUTOTRADE_TOOLS = [...STRATEGY_READ_TOOLS, ...STRATEGY_PROPOSE_TOOL
 export const PARALLEL_READ_TOOLS = ['autotrade_parallel_list', 'autotrade_parallel_compare'];
 export const PARALLEL_CONTROL_TOOLS = ['autotrade_parallel_start', 'autotrade_parallel_stop'];
 export const PARALLEL_TOOLS = [...PARALLEL_READ_TOOLS, ...PARALLEL_CONTROL_TOOLS];
+/** task-1647: the journey tools. Reads; forward-test control (paper, own bankroll); promotion PROPOSALS (never applied). */
+export const JOURNEY_READ_TOOLS = ['strategy_journey', 'strategy_forward_report'];
+export const JOURNEY_CONTROL_TOOLS = ['strategy_forward_start', 'strategy_forward_stop'];
+export const JOURNEY_PROPOSE_TOOLS = ['strategy_promote_propose'];
+export const JOURNEY_TOOLS = [...JOURNEY_READ_TOOLS, ...JOURNEY_CONTROL_TOOLS, ...JOURNEY_PROPOSE_TOOLS];
+/** Forward tests a model may start per hour (each one is a background process on the user's machine). */
+export const FORWARD_START_RATE = { perHour: 3 };
+export const defaultForwardSpawner = (home, t, env) => {
+    const bin = process.argv[1] ?? '';
+    if (!/^dexterm(\.m?js)?$/.test(basename(bin)))
+        return null;
+    const child = spawn(process.execPath, [bin, 'autotrade', 'forward', 'run', t.forwardId], { detached: true, stdio: 'ignore', env: { ...env, DEXTERM_HOME: home } });
+    child.unref();
+    return child.pid ?? null;
+};
 export const MAX_PROPOSAL_OPS = 20;
 export const BACKTEST_MAX_DAYS = 14;
 /** Backtests: one at a time, at least this far apart, and at most this many per hour per server process. */
@@ -56,7 +85,7 @@ const DAY_MS = 86_400_000;
  * to live, change the book, raise its own daily spend or lower the floor under which a bag counts as stuck.
  */
 export const STRATEGY_DENIED_FOR_MODELS = [
-    { pointer: '/mode', why: 'only you can change the mode (a model can never switch a strategy to live)' },
+    { pointer: '/mode', why: 'only you can change the mode (a model can never switch a strategy to real or live; real is armed on your own terminal)' },
     { pointer: '/bankroll', why: 'only you can change the book' },
     { pointer: '/agent/budgetUsdPerDay', why: 'only you can change the daily spend (a model can never raise its own budget)' },
     { pointer: '/execution/minExitLiquidityUsd', why: 'only you can change the stuck-bag floor' },
@@ -690,6 +719,7 @@ export class AutotradeTools {
     backtestBusy = false;
     backtestTimes = [];
     proposalTimes = [];
+    forwardTimes = [];
     constructor(o = {}) {
         this.opts = o;
         this.env = o.env ?? process.env;
@@ -710,6 +740,11 @@ export class AutotradeTools {
                 case 'strategy_propose_new': return await this.propose({ kind: 'new', id: String(args.id ?? ''), from: String(args.fromPreset ?? ''), name: args.name, ops: args.ops ?? [], why: args.why });
                 case 'strategy_backtest': return await this.backtest(args);
                 case 'autotrade_status': return await this.status();
+                case 'strategy_journey': return await this.journey(args);
+                case 'strategy_forward_start': return await this.forwardStart(args);
+                case 'strategy_forward_stop': return await this.forwardStop(args);
+                case 'strategy_forward_report': return await this.forwardReportTool(args);
+                case 'strategy_promote_propose': return await this.promotePropose(args);
                 case 'autotrade_parallel_list': return await this.parallelList();
                 case 'autotrade_parallel_compare': return await this.parallelCompare();
                 case 'autotrade_parallel_start': return await this.parallelControl(args, 'start');
@@ -852,11 +887,21 @@ export class AutotradeTools {
                 tape = at.tapeFromDoc(at.tapeFromDb(db, { since: until - days * DAY_MS, until, minPeakLiqUsd: 20_000, spanHours: 80 }));
             }
             const results = [];
+            let heldOut = null;
             for (const sub of subjects) {
-                const { report } = await at.backtest(sub.s, tape);
-                results.push({ label: sub.label, ...compactReport(report) });
+                const full = await at.backtest(sub.s, tape);
+                results.push({ label: sub.label, ...compactReport(full.report) });
+                // task-1647: a stored strategy's backtest is its journey evidence: the same rules on each half of the split.
+                if (args.id !== undefined) {
+                    const { evidence } = await at.backtestEvidence(sub.s, tape, { by: this.actor, now: t, days, full });
+                    at.recordBacktestEvidence(this.home(), evidence);
+                    heldOut = { cutoff: evidence.heldOut.cutoff, train: evidence.heldOut.train, test: evidence.heldOut.test, verdict: evidence.verdict, claim: evidence.claim, rulesHash: evidence.rulesHash };
+                }
             }
-            return { paper: true, readOnly: true, days, tape: { source: tape.source, mints: tape.mints.length, ticks: tape.ticks.length }, results, limits: at.DATA_LIMITS, note: 'A backtest on recorded history with modelled fills, not a prediction. Nothing was saved. Quote the trade count: small n means little.' };
+            return {
+                paper: true, readOnly: true, days, tape: { source: tape.source, mints: tape.mints.length, ticks: tape.ticks.length }, results, ...(heldOut ? { heldOut } : {}), limits: at.DATA_LIMITS,
+                note: `A backtest on recorded history with modelled fills, not a prediction. ${heldOut ? 'The held-out split (the newest 30% of coins) is recorded as this strategy\'s backtest evidence for its journey; the strategy itself was not changed. Gain wording only when heldOut.claim is true.' : 'Nothing was saved.'} Quote the trade count: small n means little.`,
+            };
         }
         finally {
             this.backtestBusy = false;
@@ -873,6 +918,124 @@ export class AutotradeTools {
             pendingProposals: pending.map((p) => ({ proposalId: p.proposalId, id: p.id, kind: p.kind, riskDelta: p.riskDelta, createdAt: new Date(p.createdAt).toISOString() })),
         };
     }
+    // ───────────────────────────── the journey (task-1647) ─────────────────────────────
+    async userStrategy(id) {
+        const { at } = await this.eng();
+        if (typeof id !== 'string' || !at.STRATEGY_ID.test(id))
+            return { error: 'id must be a strategy id from strategy_list' };
+        const store = await this.store();
+        const got = store.get(id);
+        if (!got)
+            return { error: `no strategy ${id} (strategy_list shows the ids)` };
+        if (got.source !== 'user')
+            return { error: `${id} is a shipped preset: propose a copy first (strategy_propose_new), the user applies it, then work on the copy` };
+        if (!got.ok)
+            return { error: `${id} does not validate: ${got.errors.map(at.fmtIssue).join('; ')}` };
+        return { s: got.strategy, raw: store.raw(id) };
+    }
+    async journey(args) {
+        const { at } = await this.eng();
+        const r = await this.userStrategy(args.id);
+        if ('error' in r)
+            return r;
+        const home = this.home();
+        const v = at.journeyView(home, r.s, { armedHash: at.loadArmings(home)[r.s.id]?.strategyHash ?? null });
+        const fw = at.findForwardTest(home, r.s.id, this.now());
+        const pending = new at.PromotionFiles(home).list({ status: 'pending', id: r.s.id });
+        return {
+            paper: r.s.mode !== 'real', id: v.id, version: v.version, rulesHash: v.rulesHash, mode: v.mode, stage: v.stage,
+            rungs: v.rungs.map((x) => ({ stage: x.stage, ok: x.ok, detail: cleanText(x.detail, 300) })), next: v.next, notes: v.notes.map((n) => cleanText(n, 200)),
+            forward: fw ? { forwardId: fw.forwardId, state: at.liveState(fw, this.now()), window: fw.window, progress: fw.progress, counts: fw.rulesHash === v.rulesHash && fw.state === 'done' && fw.source.startsWith('live') } : null,
+            pendingPromotions: pending.map((p) => ({ proposalId: p.proposalId, to: p.to, actor: p.actor })),
+            note: 'The ladder is draft → backtested → forward-tested → always-on → real, one rung at a time, each on evidence measured on these exact rules. Backtest with strategy_backtest, forward-test with strategy_forward_start, then propose a promotion with strategy_promote_propose; the user applies it. Never claim a result the evidence does not show.',
+        };
+    }
+    async forwardStart(args) {
+        const { at } = await this.eng();
+        const r = await this.userStrategy(args.id);
+        if ('error' in r)
+            return r;
+        const home = this.home();
+        const t = this.now();
+        while (this.forwardTimes.length && t - this.forwardTimes[0] > 3_600_000)
+            this.forwardTimes.shift();
+        if (this.forwardTimes.length >= FORWARD_START_RATE.perHour)
+            return { error: `at most ${FORWARD_START_RATE.perHour} forward tests started per hour`, reason: 'rate-limited' };
+        const v = at.journeyView(home, r.s, {});
+        if (!v.backtest)
+            return { error: `${r.s.id} has no backtest with the held-out split on its current rules: run strategy_backtest {id} first (the ladder is backtest, then forward test)`, reason: 'skip-refused' };
+        const hours = args.hours === undefined ? null : Number(args.hours);
+        const trades = args.trades === undefined ? null : Number(args.trades);
+        // No bankroll, no mode, no source: a model's forward test is always paper, live data, the strategy's own bankroll.
+        const c = at.createForwardTest(home, r.s, r.raw, { hours: hours ?? (trades === null ? 24 : null), trades, by: this.actor, now: t, source: 'live' });
+        if (!c.ok)
+            return { error: cleanText(c.why, 300) };
+        const pid = (this.opts.forwardSpawner ?? defaultForwardSpawner)(home, c.test, this.env);
+        if (!pid) {
+            at.saveForwardTest(home, { ...c.test, state: 'failed', endedAt: t, endReason: 'could not start the host from the chat' });
+            return { error: `could not start the forward test from here; the user can start it in a terminal: dexterm autotrade forward start ${r.s.id}${hours ? ` --hours ${hours}` : ''}${trades ? ` --trades ${trades}` : ''}` };
+        }
+        this.forwardTimes.push(t);
+        return {
+            paper: true, started: true, forwardId: c.test.forwardId, id: r.s.id, version: c.test.version, window: c.test.window, bankrollUsd: c.test.bankrollUsd,
+            note: `A FORWARD TEST runs in the background on LIVE data, on paper, with ${r.s.id}'s own bankroll and its own run file, until its window ends (${at.windowText(c.test.window)}). Read it with strategy_forward_report; stop it with strategy_forward_stop. Say nothing about results until it ends, and then only with the trade counts: under 20 closed trades it proves nothing.`,
+        };
+    }
+    async forwardRef(args) {
+        const { at } = await this.eng();
+        const ref = args.forwardId !== undefined ? String(args.forwardId) : args.id !== undefined ? String(args.id) : '';
+        if (!ref)
+            return { error: 'pass id (a strategy id) or forwardId' };
+        const t = at.findForwardTest(this.home(), ref, this.now());
+        return t ? { t } : { error: `no forward test for ${cleanText(ref, 40)}` };
+    }
+    async forwardStop(args) {
+        const { at } = await this.eng();
+        const f = await this.forwardRef(args);
+        if ('error' in f)
+            return f;
+        const r = at.requestForwardStop(this.home(), f.t.forwardId, this.actor, this.now());
+        if (!r.ok)
+            return { error: cleanText(r.why, 200) };
+        return { paper: true, stopRequested: true, already: r.already, forwardId: f.t.forwardId, note: 'It flattens at its next tick, writes its report and ends. A forward test stopped early is shown in the journey but does not count as the forward-tested rung.' };
+    }
+    async forwardReportTool(args) {
+        const { at } = await this.eng();
+        const f = await this.forwardRef(args);
+        if ('error' in f)
+            return f;
+        const r = at.forwardReport(this.home(), f.t, this.now());
+        return {
+            paper: true, readOnly: true, forwardId: r.forwardId, id: r.strategyId, version: r.version, state: r.state, source: r.source, window: r.window, elapsed: r.elapsed,
+            endReason: r.endReason ? cleanText(r.endReason, 200) : null, progress: r.progress, metrics: r.metrics,
+            comparison: { rows: r.comparison.rows, verdict: r.comparison.verdict, claim: r.comparison.claim, sampleOk: r.comparison.sampleOk },
+            note: r.comparison.claim ? 'Both halves of the evidence agree; still quote the trade counts and say it is paper with modelled fills.' : 'No performance claim: report the numbers with their trade counts and the verdict lines as they are. Paper, modelled fills, not financial advice.',
+        };
+    }
+    async promotePropose(args) {
+        const { at } = await this.eng();
+        const r = await this.userStrategy(args.id);
+        if ('error' in r)
+            return r;
+        const t = this.now();
+        while (this.proposalTimes.length && t - this.proposalTimes[0] > 600_000)
+            this.proposalTimes.shift();
+        if (this.proposalTimes.length >= 10)
+            return { error: 'proposal rate limit: at most 10 proposals per 10 minutes', reason: 'rate-limited' };
+        const home = this.home();
+        const p = at.proposePromotion(home, r.s, String(args.to ?? ''), { actor: this.actor, why: cleanText(args.why), now: t, armedHash: at.loadArmings(home)[r.s.id]?.strategyHash ?? null });
+        if (!p.ok)
+            return { ok: false, applied: false, reason: p.reason, error: cleanText(p.why, 300), note: p.reason === 'skip-refused' ? 'No rung can be skipped: do the missing step first (strategy_journey says which).' : p.reason === 'evidence-floor' ? 'Nothing was proposed. Real needs the evidence floor: a COMPLETED forward test of these exact rules with the user\'s minimum of closed paper trades, and a backtest on record. The floor is the user\'s limit: you cannot propose past it, lower it, skip it or override it. Say what is missing and stop.' : 'Nothing was proposed.' };
+        if (!p.duplicate)
+            this.proposalTimes.push(t);
+        const pr = p.proposal;
+        return {
+            ok: true, applied: false, proposalId: pr.proposalId, id: pr.id, to: pr.to, version: pr.version, card: pr.card, duplicate: p.duplicate,
+            note: pr.to === 'real'
+                ? `This is a PROPOSAL and it is NOT applied. Real mode is the user's alone: they set their own caps (dexterm autotrade signal caps set) and arm it on their own terminal with a typed phrase (dexterm autotrade promote apply ${pr.proposalId}, which hands over to signal arm). You cannot apply it, set or suggest cap values, or arm anything.`
+                : `This is a PROPOSAL and it is NOT applied. The user applies it with y on a real terminal (dexterm autotrade promote apply ${pr.proposalId}) or on the Q screen journey view; then the always-on service runs it on paper. You cannot apply it.`,
+        };
+    }
     // ───────────────────────────── parallel strategies (task-1529) ─────────────────────────────
     /** autotrade.json's strategies and, while `run --all` runs, each one's state. */
     async parallelList() {

package/dist/packages/mcp/src/engine/restrictions.js

@@ -14,7 +14,7 @@
 // never raise a cap, arm a mandate or turn live on, and no tool, MCP call or chat message changes the profile.
 import { ANALYST_ACTION_TYPES } from '../../../data/src/index.js';
 import { PAPER_NOTE_TOOLS, PAPER_READ_TOOLS, PAPER_WRITE_TOOLS, READ_ONLY_TOOLS } from "../server.js";
-import { PARALLEL_CONTROL_TOOLS, STRATEGY_PROPOSE_TOOLS } from "../autotrade-tools.js";
+import { JOURNEY_CONTROL_TOOLS, JOURNEY_PROPOSE_TOOLS, PARALLEL_CONTROL_TOOLS, STRATEGY_PROPOSE_TOOLS } from "../autotrade-tools.js";
 import { LEDGER_PROPOSE_TOOLS } from "../ledger-tools.js";
 export const RESTRICTION_LEVELS = ['observe', 'propose', 'paper', 'full'];
 export const RESTRICTION_RANK = { observe: 0, propose: 1, paper: 2, full: 3 };
@@ -65,7 +65,7 @@ export function engineToolAllowlist(level, actionTypes) {
             if (!actionTypes || actionTypes.includes(t))
                 out.add(t);
     if (allows(level, 'strategy-proposals') && !observeOnly)
-        for (const t of STRATEGY_PROPOSE_TOOLS)
+        for (const t of [...STRATEGY_PROPOSE_TOOLS, ...JOURNEY_PROPOSE_TOOLS])
             out.add(t);
     // Paper tools: the MCP server still refuses them unless the user armed a mandate and enabled agent paper trading.
     if (allows(level, 'paper-orders') && !observeOnly)
@@ -74,7 +74,7 @@ export function engineToolAllowlist(level, actionTypes) {
     // v0.1.7 integration: the other paper-side writes (start / stop / pause one listed parallel strategy, a paper
     // journal tag, a backtest request file) join at `paper`, so `paper` and `full` offer every tool the claude path has
     if (allows(level, 'paper-orders') && !observeOnly)
-        for (const t of [...PARALLEL_CONTROL_TOOLS, ...PAPER_NOTE_TOOLS, ...LEDGER_PROPOSE_TOOLS])
+        for (const t of [...PARALLEL_CONTROL_TOOLS, ...JOURNEY_CONTROL_TOOLS, ...PAPER_NOTE_TOOLS, ...LEDGER_PROPOSE_TOOLS])
             out.add(t);
     return [...out].filter((n) => !NEVER_TOOL.test(n));
 }

package/dist/packages/mcp/src/index.js

@@ -7,7 +7,7 @@ export { resolvePaperAgentDesk, paperAgentDeskDb } from "./paper-agent.js";
 export { OverlayStore, mergeOverlay, loadBundled, checkKb, checkSkill, moneyToolMentions, isMoneyToolName, parseFrontmatter, dextermHome, userKbDir, userSkillsDir, userDir, contentJournalPath, journalContent, writeOverlayFile, resetOverlayFile, templateFor, KB_LIMITS, SKILL_LIMITS, KB_ID, SKILL_NAME, KB_RULE, MONEY_TOOLS, } from "./user-content.js";
 // task-1507: the AUTOTRADE chat tools (strategy reads + proposals), the model deny-list, the risk delta and the
 // proposal files the Q screen's keypress path re-checks and applies.
-export { AutotradeTools, ProposalFiles, checkProposal, riskDelta, diffLines, screenDelta, deniedChanges, opsPolicyErrors, opsShapeErrors, proposalCardView, proposalsDir, isProposalId, cleanText, loadEngine, STRATEGY_DENIED_FOR_MODELS, STRATEGY_READ_TOOLS, STRATEGY_PROPOSE_TOOLS, AUTOTRADE_TOOLS, PARALLEL_READ_TOOLS, PARALLEL_CONTROL_TOOLS, PARALLEL_TOOLS, MAX_PROPOSAL_OPS, BACKTEST_MAX_DAYS, BACKTEST_RATE, PROPOSAL_SCHEMA, RUNNER_STATUS_SCHEMA, } from "./autotrade-tools.js";
+export { AutotradeTools, ProposalFiles, checkProposal, riskDelta, diffLines, screenDelta, deniedChanges, opsPolicyErrors, opsShapeErrors, proposalCardView, proposalsDir, isProposalId, cleanText, loadEngine, STRATEGY_DENIED_FOR_MODELS, STRATEGY_READ_TOOLS, STRATEGY_PROPOSE_TOOLS, AUTOTRADE_TOOLS, PARALLEL_READ_TOOLS, PARALLEL_CONTROL_TOOLS, PARALLEL_TOOLS, JOURNEY_READ_TOOLS, JOURNEY_CONTROL_TOOLS, JOURNEY_PROPOSE_TOOLS, JOURNEY_TOOLS, FORWARD_START_RATE, defaultForwardSpawner, MAX_PROPOSAL_OPS, BACKTEST_MAX_DAYS, BACKTEST_RATE, PROPOSAL_SCHEMA, RUNNER_STATUS_SCHEMA, } from "./autotrade-tools.js";
 export { buildDossier } from "./dossier.js";
 // task-1530: the trade-ledger tools (reads + the backtest request), and the request files the CLI runs or dismisses.
 export { LedgerTools, LEDGER_TOOLS, LEDGER_READ_TOOLS, LEDGER_PROPOSE_TOOLS, tradeView, filterFromArgs } from "./ledger-tools.js";