dexterm-cli 0.1.7 → 0.2.1

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";

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

@@ -11,9 +11,17 @@
 //                               every candidate of a run (what the skips turned into)
 //   telegram_status    observe  the Telegram connector's settings: enabled, paired chats (a count), approvals, notify
 //   trading_status     observe  where live trading happens (task-1571: not in dexterm; it holds no key and places no
-//                               live order) and whether the panic switch is engaged
+//                               live order), whether the panic switch is engaged, and real mode's state (task-1645)
+//   trade_fire_feed      observe  task-1645: the MCP channel of real mode: the LIVE TRADE FIRE signals of the feed
+//                               (autotrade/real/mcp-feed.jsonl) after a nonce, and real mode's status. Reading is all it
+//                               does: no tool arms real mode, changes a cap, lifts the kill switch or records a receipt
+//   trading_limits     observe  task-1654: real mode's limits in force (for a strategy / account / mode), where each
+//                               number comes from, what each limit does, today's counters and the executor's health
 //   backtest_requests  observe  the backtests this agent asked for, and their results once the user ran them
 //   backtest_request   propose  ask the user to run a longer backtest (a request file; the user runs or dismisses it)
+//   limits_propose     propose  task-1654: a limits change as a DIFF CARD (old -> new, which numbers it raises, the
+//                               exact command the user would type). It writes nothing at all: only the user applies a
+//                               change, on their own terminal (`dexterm autotrade limits set`; a raise is typed)
 //
 // Nothing here can trade, sign, change a cap, enable live or touch a key: the ledger is read through
 // `@dexterm/autotrade`'s loader (pure file reads, loaded lazily: @dexterm/autotrade imports this package). Text that
@@ -26,10 +34,10 @@ import { dextermHome } from "./user-content.js";
 import { BacktestRequests, MAX_PENDING_REQUESTS, REQUEST_MAX_DAYS, REQUEST_RATE_PER_HOUR } from "./backtest-requests.js";
 export const LEDGER_READ_TOOLS = [
     'ledger_trades', 'ledger_positions', 'ledger_equity', 'ledger_summary', 'ledger_compare',
-    'candidate_dossier', 'outcomes_lookup', 'telegram_status', 'trading_status', 'backtest_requests',
+    'candidate_dossier', 'outcomes_lookup', 'telegram_status', 'trading_status', 'trade_fire_feed', 'trading_limits', 'backtest_requests',
 ];
 /** Write-shaped (a request file), so not on the read-only surface a skill may name. */
-export const LEDGER_PROPOSE_TOOLS = ['backtest_request'];
+export const LEDGER_PROPOSE_TOOLS = ['backtest_request', 'limits_propose'];
 export const LEDGER_TOOLS = [...LEDGER_READ_TOOLS, ...LEDGER_PROPOSE_TOOLS];
 const MINT = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 const RUN_ID = /^[0-9TZ]+-[a-z][a-z0-9-]{1,31}-[0-9a-f]{4}$/;
@@ -64,10 +72,10 @@ export function filterFromArgs(a, now) {
         return allowed.includes(a[k]) ? a[k] : false;
     };
     const source = pick('source', ['paper', 'desk', 'autotrade', 'live']);
-    const mode = pick('mode', ['paper', 'devnet', 'live']);
+    const mode = pick('mode', ['paper', 'devnet', 'live', 'real']);
     const status = pick('status', ['open', 'closed']);
     if (source === false || mode === false || status === false)
-        return { ok: false, error: 'source is paper|desk|autotrade|live, mode is paper|devnet|live, status is open|closed' };
+        return { ok: false, error: 'source is paper|desk|autotrade|live, mode is paper|devnet|live|real, status is open|closed' };
     if (source)
         f.source = source;
     if (mode)
@@ -135,6 +143,9 @@ export class LedgerTools {
                 case 'outcomes_lookup': return await this.outcomes(args);
                 case 'telegram_status': return this.telegram();
                 case 'trading_status': return this.trading();
+                case 'trade_fire_feed': return this.signals(args);
+                case 'trading_limits': return await this.limits(args);
+                case 'limits_propose': return await this.limitsPropose(args);
                 case 'backtest_requests': return this.requests();
                 case 'backtest_request': return await this.request(args);
                 default: return { error: `unknown ledger tool ${name}` };
@@ -154,7 +165,7 @@ export class LedgerTools {
         const rows = filterTrades(v.trades, filter);
         const integrity = { ledger: v.file.check.ok ? `verified, ${v.file.events.length} events` : `FAILS its check at line ${v.file.check.at}: ${v.file.check.error}`, pendingFromSources: v.pending.length, problems: v.sources.filter((s) => s.problem).map((s) => s.problem) };
         const modes = [...new Set(rows.map((t) => t.walletMode))];
-        const base = { readOnly: true, modes, integrity, note: modes.length > 1 ? 'PAPER, DEVNET and LIVE trades are in this set: filter by mode before comparing results.' : modes.includes('paper') ? 'PAPER (simulated) trades: never present them as results.' : undefined };
+        const base = { readOnly: true, modes, integrity, note: modes.length > 1 ? 'PAPER, REAL, DEVNET and LIVE trades are in this set: filter by mode before comparing results.' : modes.includes('paper') ? 'PAPER (simulated) trades: never present them as results.' : modes.includes('real') ? 'REAL-mode trades: dexterm\'s model of the trades it signalled to the user\'s executor; the executor\'s receipts are the real fills.' : undefined };
         if (name === 'ledger_trades' || name === 'ledger_positions') {
             const limit = Math.min(200, Math.max(1, Number.isInteger(args.limit) ? Number(args.limit) : 50));
             const newest = [...rows].sort((a, b) => b.openedAt - a.openedAt).slice(0, limit);
@@ -292,13 +303,150 @@ export class LedgerTools {
     // ───────────────────────────── live trading (task-1571: not in dexterm) ───────────────
     trading() {
         const panic = existsSync(join(this.home(), 'trading.panic'));
+        const real = this.realState();
         return {
             readOnly: true,
-            liveTrading: 'not in dexterm: dexterm holds no key, signs nothing and places no live order. Live trading happens in the Telegram trading bot the user chose, which holds its own wallet; dexterm only sends alerts and run control to the user\'s own bot (telegram_status).',
+            liveTrading: 'not in dexterm: dexterm holds no key, signs nothing and places no live order. Live trading happens in the Telegram trading bot (or script) the user chose, which holds its own wallet; dexterm only sends alerts, run control and, in real mode, LIVE TRADE FIRE signals to the user\'s own executor (telegram_status, trade_fire_feed).',
             paperTrading: 'local: the paper ticket, paper accounts and paper autotrade runs (ledger_* tools)',
+            realMode: `${real.armed.length} strategy(ies) armed for real mode by the user on their own terminal${real.kill ? `; the real-mode kill switch is ON (${real.kill})` : ''}. Only the user arms, disarms, sets caps or lifts the kill switch, on their own terminal; no tool can.`,
             panicSwitch: panic ? 'engaged (autotrade runs and the paper agent desk are halted; only `dexterm wallet resume` in a terminal clears it)' : 'off',
         };
     }
+    // ───────────────────────────── real mode (task-1645) ─────────────────────────────
+    readJson(path) {
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Real mode's state from its files (pure reads; ids and numbers only). */
+    realState() {
+        const dir = join(this.home(), 'autotrade', 'real');
+        const arming = this.readJson(join(dir, 'arming.json'));
+        const armed = Object.values((arming?.armed ?? {}))
+            .filter((a) => typeof a.strategyId === 'string' && /^[a-z][a-z0-9-]{1,31}$/.test(a.strategyId))
+            .map((a) => ({ id: String(a.strategyId), version: String(a.version ?? '').slice(0, 16), accountId: String(a.accountId ?? '').replace(/[^a-z0-9_-]/g, '').slice(0, 32) }));
+        const killFile = join(dir, 'kill.json');
+        const k = existsSync(killFile) ? this.readJson(killFile) : null;
+        // task-1654: the caps are four of the limits (limits.json global, else card A's caps.json).
+        const lim = this.readJson(join(dir, 'limits.json'))?.global;
+        const caps = (lim ? Object.fromEntries(['perTradeSol', 'dailySol', 'buysPerDay', 'maxOpenPositions'].filter((k) => typeof lim[k] === 'number').map((k) => [k, lim[k]])) : undefined) ?? this.readJson(join(dir, 'caps.json'))?.caps;
+        const capsNum = caps ? Object.fromEntries(Object.entries(caps).filter(([, v]) => typeof v === 'number')) : null;
+        const n = Number(this.readJson(join(dir, 'nonce.json'))?.last);
+        return { armed, kill: existsSync(killFile) ? cleanLedgerText(k?.reason ?? 'engaged', 80) || 'engaged' : null, caps: capsNum, lastNonce: Number.isSafeInteger(n) ? n : null };
+    }
+    signals(args) {
+        const after = Number(args.after_nonce ?? 0);
+        const limit = Number(args.limit ?? 50);
+        if (!Number.isSafeInteger(after) || after < 0)
+            return { error: 'after_nonce is a whole number >= 0' };
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+            return { error: 'limit is a whole number from 1 to 100' };
+        const feed = join(this.home(), 'autotrade', 'real', 'mcp-feed.jsonl');
+        const out = [];
+        let feedOn = false;
+        if (existsSync(feed)) {
+            feedOn = true;
+            for (const l of readFileSync(feed, 'utf8').split('\n')) {
+                if (!l.trim())
+                    continue;
+                let x;
+                try {
+                    x = JSON.parse(l);
+                }
+                catch {
+                    continue;
+                }
+                if (x.schema !== 'dexterm-trade-fire/1' || typeof x.nonce !== 'number' || x.nonce <= after)
+                    continue;
+                // The signal as dexterm wrote it; the only token text in it is the symbol, already reduced to [A-Za-z0-9._$-].
+                out.push({ ...x, symbol: typeof x.symbol === 'string' ? x.symbol.replace(/[^A-Za-z0-9._$-]/g, '').slice(0, 16) : undefined });
+                if (out.length >= limit)
+                    break;
+            }
+        }
+        const st = this.realState();
+        return {
+            readOnly: true, schema: 'dexterm-trade-fire/1', signals: out, nextAfterNonce: out.length ? out[out.length - 1].nonce : after,
+            realMode: { armed: st.armed, kill: st.kill, caps: st.caps, lastNonce: st.lastNonce, mcpFeed: feedOn ? 'on' : 'off (the user enables it: dexterm autotrade signal channels --mcp on)' },
+            rules: 'An executor acts only on its own accountId, ignores a signal after expiresAt, and dedupes by nonce (delivery is at-least-once). type "halted" ends a run; type "test" is never traded. The user records what was done with `dexterm autotrade receipt`; this tool changes nothing.',
+        };
+    }
+    // ───────────────────────────── limits (task-1654) ─────────────────────────────
+    limitsContext(args) {
+        const id = (v, name) => (v === undefined ? '-' : typeof v === 'string' && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(v) ? v : { error: `${name} is an id ([a-z0-9._-], 64 max)` });
+        const strategyId = id(args.strategy, 'strategy');
+        if (typeof strategyId !== 'string')
+            return strategyId;
+        const accountId = id(args.account, 'account');
+        if (typeof accountId !== 'string')
+            return accountId;
+        if (args.mode !== undefined && args.mode !== 'real' && args.mode !== 'paper')
+            return { error: 'mode is real or paper' };
+        return { strategyId, accountId, mode: args.mode === 'paper' ? 'paper' : 'real' };
+    }
+    async limits(args) {
+        const c = this.limitsContext(args);
+        if ('error' in c)
+            return c;
+        const at = await import('../../autotrade/src/index.js');
+        const home = this.home();
+        const l = at.loadLimits(home);
+        const doc = l.ok ? l.doc : null;
+        const e = at.effectiveLimits(doc, c);
+        const risk = at.loadRiskState(home, this.now());
+        const ex = at.executorHealth(home, { now: this.now(), windowMin: e.values.executorSilenceMin ?? null });
+        return {
+            readOnly: true, context: c, applies: e.applies,
+            state: l.ok ? (l.source === 'migrated' ? 'migrated from caps.json' : l.unjournaled ? 'changed outside dexterm (a real run refuses it if it raises anything)' : 'saved by the user') : l.missing ? 'not set yet: placeholder defaults (real mode does not arm on them silently)' : 'unreadable: real buys are refused',
+            limits: at.LIMIT_FIELDS.map((f) => ({ key: f.key, group: f.group, unit: f.unit, kind: f.dir === 'max' ? 'cap (smaller is stricter)' : 'floor (larger is stricter)', value: e.values[f.key] ?? null, from: e.from[f.key] ?? null, placeholder: at.DEFAULT_LIMITS[f.key] ?? null, what: f.help })),
+            today: { day: risk.day, buys: risk.buys, buySol: risk.buySol, realizedSol: risk.dayPnlSol, lossStreak: risk.lossStreak, pausedUntil: iso(risk.pausedUntil), breaker: risk.breaker ? { at: iso(risk.breaker.at), drawdownSol: risk.breaker.drawdownSol } : null },
+            executor: at.healthLine(ex),
+            rules: 'Limits live outside the model. The effective number is the placeholder default replaced by the user\'s global value, then the STRICTER of every scope that sets it (mode, strategy, account). No tool changes them: limits_propose returns a diff card for the user to apply on their own terminal (raising needs their typed confirmation). The defaults are placeholders, not advice.',
+        };
+    }
+    async limitsPropose(args) {
+        const at = await import('../../autotrade/src/index.js');
+        const scope = typeof args.scope === 'string' ? args.scope : 'global';
+        const changes = args.changes;
+        if (!changes || typeof changes !== 'object' || Array.isArray(changes) || !Object.keys(changes).length || Object.keys(changes).length > 24)
+            return { error: 'changes is an object of 1 to 24 limits: { "perTradeSol": 0.1, "dailyLossSol": null }' };
+        // The agent's own reason is returned apart from the card, firewalled: the card is engine-made lines only.
+        const why = typeof args.why === 'string' ? fw(args.why.slice(0, 200), 'limits-why') : null;
+        const home = this.home();
+        const l = at.loadLimits(home);
+        const cur = l.ok ? l.doc : at.emptyLimits();
+        const next = structuredClone(cur);
+        delete next.migratedFrom;
+        const ref = at.scopeRef(next, scope, true);
+        if ('error' in ref)
+            return { error: ref.error };
+        for (const [k, v] of Object.entries(changes)) {
+            if (!at.limitField(k))
+                return { error: `unknown limit "${String(k).slice(0, 40)}"` };
+            if (v !== null && (typeof v !== 'number' || !Number.isFinite(v)))
+                return { error: `${k}: a number, or null to remove it` };
+            if (v === null && !ref.isGlobal)
+                delete ref.set[k];
+            else
+                ref.set[k] = v;
+        }
+        const issues = at.validateLimits(next);
+        if (issues.length)
+            return { error: issues.map((i) => `${i.path}: ${i.msg}`).join('; ').slice(0, 400) };
+        const diff = at.diffLimits(l.ok ? cur : null, next);
+        const up = at.raises(diff);
+        const assign = Object.entries(changes).map(([k, v]) => `${k}=${v === null ? 'off' : v}`).join(' ');
+        return {
+            applied: false, proposal: true,
+            card: [`PROPOSED LIMITS CHANGE · ${scope}`, ...diff.map((d) => `  ${at.changeLine(d)}`), up.length ? `  raises ${up.length} limit(s): you would type the confirmation on your own terminal` : '  lowers only: applies at once when you run it', `  to apply it yourself: dexterm autotrade limits set --scope ${scope} ${assign}`],
+            changes: diff, raises: up.length, why,
+            command: `dexterm autotrade limits set --scope ${scope} ${assign}`,
+            note: 'Nothing was changed: no tool can change a limit. Only the user applies this, on their own terminal.',
+        };
+    }
     // ───────────────────────────── backtest requests ─────────────────────────────
     requests() {
         const rs = new BacktestRequests(this.home()).list().slice(0, 20);