dexterm-cli 0.1.7 → 0.2.0

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

@@ -225,6 +225,19 @@ export class SimBook {
         this.triggers.set(id, trigger);
         return p;
     }
+    /**
+     * 0.2.0 card B (service-recover.ts): take over a position a crashed run left open. Its open cost leaves this
+     * book's cash (it is exposure here now); the coin counts as entered, so the per-coin rules see it.
+     */
+    adopt(p) {
+        if (this.open.has(p.mint))
+            return false;
+        this.state.cashUsd -= Math.max(0, p.costUsd - p.realizedUsd);
+        (this.state.perCoin[p.mint] ??= { entries: 0, lastExit: 0 }).entries++;
+        this.open.set(p.mint, p);
+        this.triggers.set(p.id, ['resumed']);
+        return true;
+    }
     addTranche(p, fill) {
         this.state.cashUsd -= fill.usd;
         const tokens = p.tokens + fill.tokens;
@@ -289,8 +302,9 @@ export function clampEntry(book, k, req, killSwitch = false) {
     const st = book.state;
     const clamps = [];
     const no = (refused) => ({ ok: false, refused, clamps });
-    // task-1571: paper only (dexterm holds no key and places no live order).
-    if (s.mode !== 'paper')
+    // task-1571: paper only (dexterm holds no key and places no live order). task-1645: real is the same paper book; its
+    // fills become trade-fire signals for the user's own executor (the runner admits it only through the real-mode hook).
+    if (s.mode !== 'paper' && s.mode !== 'real')
         return no('mode-not-paper');
     if (killSwitch)
         return no('kill-switch');

package/dist/packages/autotrade/src/executor-health.js

@@ -0,0 +1,217 @@
+// dexterm autotrade — executor health: heartbeats, the silence pause, the loopback listener (task-1654, 0.2.0 card E).
+//
+// Your executor (or the reference kit, examples/executor/) says it is alive by appending a
+// `dexterm-executor-heartbeat/1` line to $DEXTERM_HOME/autotrade/real/executor.jsonl, by running
+// `dexterm autotrade executor heartbeat`, or by POSTing it to the optional loopback listener a real run opens
+// (`dexterm autotrade signal channels --executor-port N`: 127.0.0.1 only, the same HMAC as the webhook when a secret
+// is set, /heartbeat and /receipt, 4 KB bodies). A receipt, and an ack on the webhook or command hook, count as
+// signs of life too (the JSONL stream and the MCP feed prove nothing: dexterm writes those itself).
+//
+// When nothing has been heard for longer than the user's `executorSilenceMin` (limits.json; placeholder 15 min) a real
+// run PAUSES new buy signals and says so (run log, Telegram). Exits still go out, and the kill switch and the TTL are
+// unchanged. When the executor is heard again, buys resume and that is said too. Heartbeats are data: they never make
+// dexterm do anything except pause or resume.
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, renameSync, statSync, writeSync, fsyncSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { realDir } from "./outbox.js";
+import { appendReceipt, readReceipts, validateReceipt } from "./receipts.js";
+import { ACCOUNT_ID_RE, verifyBody } from "./signal.js";
+export const HEARTBEAT_SCHEMA = 'dexterm-executor-heartbeat/1';
+export const heartbeatPath = (home) => join(realDir(home), 'executor.jsonl');
+const ROTATE_ABOVE = 1 << 20;
+const TAIL_BYTES = 64 << 10;
+const text = (v, max) => { if (typeof v !== 'string')
+    return null; const t = v.replace(/[^\x20-\x7e]/g, '').trim().slice(0, max); return t || null; };
+export function validateHeartbeat(x) {
+    const h = x;
+    if (!h || typeof h !== 'object')
+        return { ok: false, error: 'not an object' };
+    if (h.schema !== HEARTBEAT_SCHEMA)
+        return { ok: false, error: 'schema' };
+    if (typeof h.at !== 'number' || !Number.isFinite(h.at) || h.at <= 0)
+        return { ok: false, error: 'at' };
+    const executor = text(h.executor, 32);
+    if (!executor)
+        return { ok: false, error: 'executor' };
+    if (h.accountId !== undefined && h.accountId !== null && (typeof h.accountId !== 'string' || !ACCOUNT_ID_RE.test(h.accountId)))
+        return { ok: false, error: 'accountId' };
+    if (h.lastNonce !== undefined && h.lastNonce !== null && (!Number.isSafeInteger(h.lastNonce) || h.lastNonce < 0))
+        return { ok: false, error: 'lastNonce' };
+    return { ok: true, heartbeat: { schema: HEARTBEAT_SCHEMA, at: h.at, executor, accountId: typeof h.accountId === 'string' ? h.accountId : null, dryRun: typeof h.dryRun === 'boolean' ? h.dryRun : null, lastNonce: typeof h.lastNonce === 'number' ? h.lastNonce : null, note: text(h.note, 120) } };
+}
+/** Append one heartbeat (fsync); the file is rotated to executor.1.jsonl past 1 MB. */
+export function appendHeartbeat(home, hb) {
+    const v = validateHeartbeat({ ...hb, schema: HEARTBEAT_SCHEMA });
+    if (!v.ok)
+        throw new Error(`heartbeat: ${v.error}`);
+    mkdirSync(realDir(home), { recursive: true, mode: 0o700 });
+    const p = heartbeatPath(home);
+    try {
+        if (statSync(p).size > ROTATE_ABOVE)
+            renameSync(p, join(realDir(home), 'executor.1.jsonl'));
+    }
+    catch { /* no file yet */ }
+    const fd = openSync(p, 'a', 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(v.heartbeat)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return v.heartbeat;
+}
+const hbCache = new Map();
+/** The newest valid heartbeat (reads only the last 64 KB, and only when the file changed since the last read). */
+export function lastHeartbeat(home) {
+    const p = heartbeatPath(home);
+    if (!existsSync(p))
+        return null;
+    const fd = openSync(p, 'r');
+    try {
+        const st = fstatSync(fd);
+        const size = st.size;
+        const c = hbCache.get(p);
+        if (c && c.size === size && c.mtimeMs === st.mtimeMs)
+            return c.hb;
+        const n = Math.min(size, TAIL_BYTES);
+        const buf = Buffer.alloc(n);
+        readSync(fd, buf, 0, n, size - n);
+        const lines = buf.toString('utf8').split('\n');
+        let best = null;
+        for (const l of lines) {
+            if (!l.trim())
+                continue;
+            try {
+                const v = validateHeartbeat(JSON.parse(l));
+                if (v.ok && (!best || v.heartbeat.at > best.at))
+                    best = v.heartbeat;
+            }
+            catch { /* torn or partial line */ }
+        }
+        hbCache.set(p, { size, mtimeMs: st.mtimeMs, hb: best });
+        return best;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * How the executor looks now. `ackAt` = the newest ack on the webhook or command hook (the outbox's channel health,
+ * this process); `since` = a floor for "last seen" (the run's start: a run is not paused in its first window).
+ */
+export function executorHealth(home, o) {
+    const hb = lastHeartbeat(home);
+    const receipts = o.receipts ?? readReceipts(home).receipts;
+    const last = receipts.reduce((a, r) => (!a || r.at > a.at ? r : a), null);
+    const cands = [];
+    if (hb)
+        cands.push([hb.at, 'heartbeat']);
+    if (last)
+        cands.push([last.at, 'receipt']);
+    if (o.ackAt)
+        cands.push([o.ackAt, 'ack']);
+    if (o.since)
+        cands.push([o.since, 'run-start']);
+    const best = cands.reduce((a, c) => (!a || c[0] > a[0] ? c : a), null);
+    const lags = [];
+    if (o.signal)
+        for (const r of receipts.slice(-20)) {
+            const s = o.signal(r.nonce);
+            if (s && s.id === r.signalId)
+                lags.push(Math.max(0, (r.at - s.issuedAt) / 1000));
+        }
+    lags.sort((a, b) => a - b);
+    const silentSec = best ? Math.max(0, Math.round((o.now - best[0]) / 1000)) : null;
+    const windowMin = o.windowMin ?? null;
+    return {
+        alive: windowMin === null ? null : silentSec !== null && silentSec <= windowMin * 60,
+        windowMin, lastSeenAt: best?.[0] ?? null, lastSeenBy: best?.[1] ?? null, silentSec,
+        heartbeat: hb ? { at: hb.at, executor: hb.executor, dryRun: hb.dryRun, lastNonce: hb.lastNonce } : null,
+        lastReceipt: last ? { at: last.at, nonce: last.nonce, status: last.status } : null,
+        receiptLagSec: lags.length ? Math.round(lags[Math.floor(lags.length / 2)] * 10) / 10 : null,
+    };
+}
+const ago = (sec) => (sec < 90 ? `${sec} s` : sec < 5400 ? `${Math.round(sec / 60)} min` : `${Math.round(sec / 3600)} h`);
+export function healthLine(h) {
+    const state = h.alive === null ? (h.lastSeenAt ? 'seen' : 'never seen') : h.alive ? 'ALIVE' : 'SILENT';
+    const parts = [state];
+    if (h.silentSec !== null && h.lastSeenBy && h.lastSeenBy !== 'run-start')
+        parts.push(`last ${h.lastSeenBy} ${ago(h.silentSec)} ago`);
+    else if (h.lastSeenBy === 'run-start')
+        parts.push('nothing heard since the run started');
+    if (h.heartbeat)
+        parts.push(`${h.heartbeat.executor}${h.heartbeat.dryRun ? ' (dry run)' : ''}`);
+    if (h.lastReceipt)
+        parts.push(`last receipt #${h.lastReceipt.nonce} ${h.lastReceipt.status}`);
+    if (h.receiptLagSec !== null)
+        parts.push(`receipt lag ${h.receiptLagSec} s`);
+    if (h.windowMin !== null)
+        parts.push(`pause after ${h.windowMin} min silent`);
+    return parts.join(' · ');
+}
+/**
+ * A loopback-only HTTP listener for executors that prefer to POST: /heartbeat (a heartbeat body) and /receipt (a
+ * receipt body). With a secret, the `x-dexterm-signature` header (the webhook's scheme) is required. Writes the same
+ * files the CLI and the kit append to. Never acts on anything.
+ */
+export function startExecutorListener(o) {
+    const host = o.host ?? '127.0.0.1';
+    if (!['127.0.0.1', '::1', 'localhost'].includes(host))
+        return Promise.reject(new Error('the executor listener binds to loopback only'));
+    const now = o.now ?? Date.now;
+    const server = createServer((req, res) => {
+        const reply = (code, body) => { res.writeHead(code, { 'content-type': 'text/plain' }); res.end(body); };
+        if (req.method !== 'POST' || (req.url !== '/heartbeat' && req.url !== '/receipt'))
+            return reply(404, 'POST /heartbeat or /receipt');
+        let body = '';
+        let tooBig = false;
+        req.setEncoding('utf8');
+        req.on('data', (c) => { body += c; if (body.length > 4096) {
+            tooBig = true;
+            req.destroy();
+        } });
+        req.on('end', () => {
+            if (tooBig)
+                return;
+            const secret = o.secret?.() ?? null;
+            if (secret) {
+                const v = verifyBody(secret, req.headers['x-dexterm-signature'], body, now());
+                if (!v.ok)
+                    return reply(401, v.why);
+            }
+            let raw;
+            try {
+                raw = JSON.parse(body);
+            }
+            catch {
+                return reply(400, 'not json');
+            }
+            try {
+                if (req.url === '/heartbeat') {
+                    const v = validateHeartbeat({ ...raw, schema: HEARTBEAT_SCHEMA });
+                    if (!v.ok)
+                        return reply(400, v.error);
+                    appendHeartbeat(o.home, v.heartbeat);
+                    return reply(204, '');
+                }
+                const v = validateReceipt(raw);
+                if (!v.ok)
+                    return reply(400, v.error);
+                appendReceipt(o.home, v.receipt);
+                return reply(204, '');
+            }
+            catch (e) {
+                return reply(500, e.message.slice(0, 80));
+            }
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(o.port, host, () => {
+            const a = server.address();
+            resolve({ port: typeof a === 'object' && a ? a.port : o.port, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}

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

@@ -538,7 +538,10 @@ export async function runFleet(o) {
         fl.add(now, 'member_start', { member: id, runId, why, strategyHash: spec.strategy.hash, bankroll: spec.bankroll, ...(account ? { account: account.id } : {}) });
         say(`[${id}] started (run ${runId}, ${spec.basedOn.id} v${spec.basedOn.version}, ${account ? `paper account ${account.id} ($${account.cashUsd.toFixed(2)} cash of $${account.startUsd})` : `bankroll $${spec.bankroll.usd}${spec.bankroll.sol !== undefined ? ` = ${spec.bankroll.sol} SOL` : ''}`})`);
         const ticks = hub.subscribe(runId);
+        const adopt = spec.adopt;
+        spec.adopt = undefined; // a later restart of this member (a `start` request) never adopts them twice
         l.done = runAutotrade({
+            ...(adopt?.length ? { adopt } : {}),
             strategy: spec.strategy, source: { name: o.tape?.source ?? o.source.name, ticks, startT: now }, sessions, gate, ledger, runId,
             dossier: o.dossier?.(spec), vet: o.vet?.(spec), executor: execs.executors.get(id), verbose: o.verbose ?? true, onLine: (s) => say(`[${id}] ${s}`),
             pacing, ...(account ? { account, member: id } : {}),

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

@@ -0,0 +1,355 @@
+// dexterm autotrade — FORWARD TESTS (0.2.0 card C). PAPER ONLY.
+//
+// A forward test runs one strategy, frozen at the version it started with, on the LIVE tape, on paper, for a chosen
+// window (hours, or N closed trades, whichever comes first), with its own bankroll (an isolated simulated book: no
+// paper account, no other strategy's cash) and its own run file. It is started and stopped from the chat
+// (strategy_forward_start / _stop), the Q screen's journey view and `dexterm autotrade forward start|status|stop|report`.
+//
+// It does not take the machine's run.lock: a forward test runs next to the always-on service or a foreground run, in
+// its own process (`dexterm autotrade forward run <fid>`, started detached), with its own status file and stop marker:
+//
+//   $DEXTERM_HOME/autotrade/forward/tests/<fid>.json   dexterm-forward-test/1: the frozen strategy, the window, state,
+//                                                     heartbeat, progress and, at the end, the metrics
+//   $DEXTERM_HOME/autotrade/forward/tests/<fid>.stop   the stop marker (CLI, chat, Q screen); the host flattens and ends
+//   $DEXTERM_HOME/autotrade/forward/tests/<fid>.log    the detached host's output
+//   $DEXTERM_HOME/autotrade/forward/<id>.json          the latest result line for real mode's arm panel (card A)
+//   $DEXTERM_HOME/autotrade/runs/<runId>.jsonl         the run ledger, hash-chained like every other run
+//
+// At the end of its window the host flattens (every position sold at its next tick, so the numbers are closed
+// numbers), then writes the metrics in the backtest's own shape (backtest.ts report()) and records the result in
+// the strategy's journey. Only a test that ran its whole window on live data is the "forward-tested" rung; one that
+// was stopped early, ran on a replay or died is shown, never counted. The panic file stops it like any run.
+//
+// Model spend: a forward test of an agent strategy opens sessions on the user's own engine inside the strategy's
+// budgets and runner.json's caps, like `run`. A strategy that needs a chat approval for every entry cannot be
+// forward-tested (no tap reaches a forward test). Nothing here holds a key, signs or touches a wallet.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { report } from "./backtest.js";
+import { compareForward, renderComparison, latestBacktest, loadJourney, metricsLine, metricsOf, recordForwardResult, rulesHash, runFills, usd } from "./journey.js";
+import { fileLedger, writeJsonAtomic } from "./ledger.js";
+import { runAutotrade, simExecutor } from "./runner.js";
+import { STRATEGY_ID } from "./store.js";
+import { validateStrategy } from "./strategy.js";
+export const FORWARD_SCHEMA = 'dexterm-forward-test/1';
+export const FORWARD_LIMITS = { minHours: 0.25, maxHours: 72, maxTrades: 200, maxRunning: 3, minBankrollUsd: 10, maxBankrollUsd: 1_000_000 };
+/** A running host rewrites its status at least this often; older means the host is gone. */
+export const FORWARD_HEARTBEAT_MS = 10_000;
+export const FORWARD_STALE_MS = 90_000;
+/** After the window ends, how long (tape time) the flatten may keep trying before the stream is closed. */
+export const FLATTEN_GRACE_MS = 30 * 60_000;
+/** Live data: an ended test whose stream took no step for this long is closed (the report is written). */
+export const STALL_MS = 2 * 60_000;
+export const forwardRoot = (home) => join(home, 'autotrade', 'forward');
+export const forwardTestsDir = (home) => join(forwardRoot(home), 'tests');
+const FID = /^fw_[a-z0-9]{6,12}_[a-f0-9]{8}$/;
+export const isForwardId = (x) => typeof x === 'string' && FID.test(x);
+const fpath = (home, fid, ext) => {
+    if (!isForwardId(fid))
+        throw new Error(`bad forward test id ${JSON.stringify(fid)}`);
+    return join(forwardTestsDir(home), `${fid}.${ext}`);
+};
+export const forwardTestPath = (home, fid) => fpath(home, fid, 'json');
+export const forwardStopPath = (home, fid) => fpath(home, fid, 'stop');
+export const forwardLogPath = (home, fid) => fpath(home, fid, 'log');
+/** Card A's arm panel reads `autotrade/forward/<id>.json` (summary line). */
+export const forwardSummaryPath = (home, id) => {
+    if (!STRATEGY_ID.test(id))
+        throw new Error(`bad strategy id ${JSON.stringify(id)}`);
+    return join(forwardRoot(home), `${id}.json`);
+};
+export const newForwardId = (now = Date.now()) => `fw_${now.toString(36)}_${randomBytes(4).toString('hex')}`;
+const pidAlive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+export function liveState(t, now = Date.now(), alive = pidAlive) {
+    if (t.state !== 'starting' && t.state !== 'running')
+        return t.state;
+    if (t.state === 'starting')
+        return now - t.createdAt > FORWARD_STALE_MS && (!t.pid || !alive(t.pid)) ? 'lost' : 'starting';
+    if (t.pid && !alive(t.pid))
+        return 'lost';
+    return t.heartbeatAt && now - t.heartbeatAt > FORWARD_STALE_MS ? 'lost' : 'running';
+}
+export function loadForwardTest(home, fid) {
+    if (!isForwardId(fid))
+        return null;
+    const p = forwardTestPath(home, fid);
+    if (!existsSync(p))
+        return null;
+    try {
+        const d = JSON.parse(readFileSync(p, 'utf8'));
+        return d.schema === FORWARD_SCHEMA && d.forwardId === fid ? d : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveForwardTest(home, t) {
+    mkdirSync(forwardTestsDir(home), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(forwardTestPath(home, t.forwardId), t);
+}
+/** Newest first. */
+export function listForwardTests(home, filter = {}) {
+    const dir = forwardTestsDir(home);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => loadForwardTest(home, f.slice(0, -5))).filter((t) => !!t && (!filter.strategyId || t.strategyId === filter.strategyId))
+        .sort((a, b) => b.createdAt - a.createdAt);
+}
+export const isActive = (t, now = Date.now()) => { const s = liveState(t, now); return s === 'starting' || s === 'running'; };
+/** A forward test id, or a strategy id (its running test, else its newest). */
+export function findForwardTest(home, ref, now = Date.now()) {
+    if (isForwardId(ref))
+        return loadForwardTest(home, ref);
+    if (!STRATEGY_ID.test(ref))
+        return null;
+    const all = listForwardTests(home, { strategyId: ref });
+    return all.find((t) => isActive(t, now)) ?? all[0] ?? null;
+}
+/**
+ * Freeze a strategy into a new forward test (state `starting`); the caller then starts its host. Refuses a window
+ * outside the limits, a second running test of the same strategy, more than FORWARD_LIMITS.maxRunning at once,
+ * mode live, and a strategy that needs a chat approval for every entry.
+ */
+export function createForwardTest(home, s, raw, o) {
+    const now = o.now ?? Date.now();
+    if (s.mode === 'live')
+        return { ok: false, why: `${s.id} is mode live, which does not run (dexterm holds no key and places no live order)` };
+    if (s.entry.decide === 'agent+approve')
+        return { ok: false, why: `${s.id} needs a chat approval for every entry (entry.decide "agent+approve"); no approval reaches a forward test, so it could never enter. Make a copy with decide "agent" or "auto" to forward-test it` };
+    const hours = o.hours ?? null;
+    const trades = o.trades ?? null;
+    if (hours === null && trades === null)
+        return { ok: false, why: 'a forward test needs a window: hours, a number of closed trades, or both (whichever comes first ends it)' };
+    if (hours !== null && !(Number.isFinite(hours) && hours >= FORWARD_LIMITS.minHours && hours <= FORWARD_LIMITS.maxHours))
+        return { ok: false, why: `hours must be from ${FORWARD_LIMITS.minHours} to ${FORWARD_LIMITS.maxHours}` };
+    if (trades !== null && !(Number.isInteger(trades) && trades >= 1 && trades <= FORWARD_LIMITS.maxTrades))
+        return { ok: false, why: `trades must be a whole number from 1 to ${FORWARD_LIMITS.maxTrades}` };
+    const bankrollUsd = o.bankrollUsd ?? s.bankroll.startUsd;
+    if (!(Number.isFinite(bankrollUsd) && bankrollUsd >= FORWARD_LIMITS.minBankrollUsd && bankrollUsd <= FORWARD_LIMITS.maxBankrollUsd))
+        return { ok: false, why: `the paper bankroll must be from $${FORWARD_LIMITS.minBankrollUsd} to $${FORWARD_LIMITS.maxBankrollUsd}` };
+    const running = listForwardTests(home).filter((t) => isActive(t, now));
+    const same = running.find((t) => t.strategyId === s.id);
+    if (same)
+        return { ok: false, why: `${s.id} already has a forward test running (${same.forwardId}); stop it first or read its report` };
+    if (running.length >= FORWARD_LIMITS.maxRunning)
+        return { ok: false, why: `${running.length} forward tests are already running (at most ${FORWARD_LIMITS.maxRunning} at once)` };
+    // The frozen document: always paper (a real strategy forward-tests as its paper twin), the test's own bankroll.
+    const doc = { ...structuredClone(raw), mode: 'paper', bankroll: { ...raw.bankroll, startUsd: bankrollUsd } };
+    const v = validateStrategy(doc);
+    if (!v.ok)
+        return { ok: false, why: `${s.id} does not validate as a paper forward test: ${v.errors.map((e) => `${e.path} ${e.msg}`).join('; ')}` };
+    const test = {
+        schema: FORWARD_SCHEMA, forwardId: newForwardId(now), strategyId: s.id, version: s.version, hash: s.hash, rulesHash: rulesHash(s), doc, bankrollUsd,
+        window: { hours, trades }, createdAt: now, by: o.by, source: o.source ?? 'live', stub: !!o.stub, msPerTick: o.msPerTick ?? null,
+        state: 'starting', pid: null, runId: null, startedAt: null, endsAt: null, heartbeatAt: null, endedAt: null, endReason: null, progress: null, metrics: null, problems: [],
+    };
+    saveForwardTest(home, test);
+    return { ok: true, test };
+}
+/** Ask a forward test to end (the host flattens and writes its report). Idempotent. */
+export function requestForwardStop(home, fid, by, now = Date.now()) {
+    const t = loadForwardTest(home, fid);
+    if (!t)
+        return { ok: false, why: `no forward test ${fid}` };
+    const st = liveState(t, now);
+    if (st !== 'starting' && st !== 'running')
+        return { ok: false, why: `${fid} is not running (${st})` };
+    const p = forwardStopPath(home, fid);
+    const already = existsSync(p);
+    if (!already)
+        writeFileSync(p, `${JSON.stringify({ at: now, by })}\n`, { mode: 0o600 });
+    return { ok: true, already, test: t };
+}
+export function forwardStopRequested(home, fid) {
+    const p = forwardStopPath(home, fid);
+    if (!existsSync(p))
+        return null;
+    try {
+        const d = JSON.parse(readFileSync(p, 'utf8'));
+        return { at: Number(d.at) || 0, by: typeof d.by === 'string' ? d.by.slice(0, 40) : 'unknown' };
+    }
+    catch {
+        return { at: 0, by: 'unknown' };
+    }
+}
+/** Mark a test whose host is gone as failed (a reader that finds it `lost` may call this). */
+export function markLost(home, t, now = Date.now()) {
+    const next = { ...t, state: 'failed', endedAt: now, endReason: 'the forward test host stopped without a report (crash, logout or kill)' };
+    saveForwardTest(home, next);
+    recordForwardResult(home, resultOf(next));
+    return next;
+}
+function resultOf(t) {
+    const state = t.state === 'done' || t.state === 'stopped' ? t.state : 'failed';
+    return {
+        kind: 'forward', forwardId: t.forwardId, id: t.strategyId, version: t.version, rulesHash: t.rulesHash, startedAt: t.startedAt ?? t.createdAt, endedAt: t.endedAt ?? Date.now(),
+        // Only a test on live data can be the forward-tested rung: a replay is a backtest in disguise.
+        state: state === 'done' && !t.source.startsWith('live') ? 'stopped' : state,
+        endReason: state === 'done' && !t.source.startsWith('live') ? `${t.endReason ?? 'window reached'} (on a replay, which does not count as a forward test)` : (t.endReason ?? ''),
+        window: t.window, source: t.source, metrics: t.metrics,
+    };
+}
+const dur = (ms) => { const m = Math.max(0, Math.round(ms / 60_000)); return m < 60 ? `${m} min` : `${Math.floor(m / 60)} h ${m % 60} min`; };
+export const windowText = (w) => [w.hours !== null ? `${w.hours} h` : '', w.trades !== null ? `${w.trades} closed trades` : ''].filter(Boolean).join(' or ') + (w.hours !== null && w.trades !== null ? ' (whichever first)' : '');
+/** The forward test next to the backtest (held-out split) of the same rules, from the journey file. */
+export function forwardReport(home, t, now = Date.now()) {
+    const state = liveState(t, now);
+    const bt = latestBacktest(loadJourney(home, t.strategyId), t.rulesHash);
+    const comparison = compareForward(bt, t.metrics);
+    const elapsed = t.startedAt ? dur((t.endedAt ?? now) - t.startedAt) : '0 min';
+    const lines = [
+        `FORWARD TEST ${t.forwardId} · ${t.strategyId} v${t.version} · PAPER · ${t.source} · own bankroll $${t.bankrollUsd}`,
+        `  state ${state.toUpperCase()}${t.endReason ? ` (${t.endReason})` : ''} · window ${windowText(t.window)} · ran ${elapsed}`,
+        t.progress && !t.metrics ? `  so far: ${t.progress.closed} closed · ${t.progress.open} open · equity $${t.progress.equityUsd.toFixed(2)} (${usd(t.progress.netUsd)}) · ${t.progress.candidates} candidates` : '',
+        t.metrics ? `  result: ${metricsLine(t.metrics)}` : '',
+        ...(t.metrics || bt ? ['  forward vs backtest of the same rules (paper, modelled fills; not a prediction, not financial advice):', ...renderComparison(comparison)] : []),
+        t.source.startsWith('live') ? '' : '  NOTE: this ran on a replay, so it is not a forward test of live data and does not count toward the journey',
+    ].filter(Boolean);
+    return { forwardId: t.forwardId, strategyId: t.strategyId, version: t.version, state, source: t.source, window: windowText(t.window), elapsed, endReason: t.endReason, progress: t.progress, metrics: t.metrics, comparison, lines };
+}
+/**
+ * Run a `starting` forward test to its end in this process: own ledger, own book (the frozen paper strategy and its
+ * bankroll), the window, the stop marker and the panic file; then the metrics, the journey record and the summary.
+ */
+export async function hostForward(o) {
+    const { home, forwardId } = o;
+    const clock = o.now ?? Date.now;
+    const say = o.onLine ?? (() => { });
+    let t = loadForwardTest(home, forwardId);
+    if (!t)
+        return { ok: false, why: `no forward test ${forwardId}` };
+    if (!o.source === !o.tape)
+        return { ok: false, why: 'a forward test runs on one live source or one replay tape' };
+    const srcName = o.source?.name ?? `replay ${o.tape.source}`;
+    if (t.state !== 'starting')
+        return { ok: false, why: `${forwardId} is ${t.state}; a forward test runs once` };
+    const v = validateStrategy(t.doc);
+    if (!v.ok || v.strategy.mode !== 'paper')
+        return { ok: false, why: `${forwardId}: the frozen strategy does not validate as paper` };
+    const strategy = v.strategy;
+    const runId = `${new Date(clock()).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '')}-fwd-${strategy.id}-${forwardId.slice(-4)}`;
+    let closed = 0;
+    const { ledger, files } = fileLedger(home, runId, (e) => { if (e.kind === 'trade_closed')
+        closed++; });
+    const startedAt = clock();
+    t = { ...t, state: 'running', pid: o.pid ?? process.pid, runId, startedAt, heartbeatAt: startedAt };
+    saveForwardTest(home, t);
+    ledger.add(startedAt, 'forward_start', { forwardId, strategy: strategy.id, version: t.version, rulesHash: t.rulesHash, window: t.window, bankrollUsd: t.bankrollUsd, source: srcName, by: t.by });
+    say(`forward test ${forwardId} · ${strategy.id} v${t.version} · PAPER · ${srcName} · own bankroll $${t.bankrollUsd} · window ${windowText(t.window)} · run ${runId}`);
+    // The window clock: tape time on a tape or a lockstep feed; WALL time on live data, where a cached row keeps the
+    // last tick's time and the tape clock can stall (an hours window measured on it might never close).
+    const wall = !o.tape && (o.pacing?.mode ?? 'live') === 'live';
+    let tapeT = null;
+    let endsAt = wall && t.window.hours !== null ? startedAt + t.window.hours * 3_600_000 : null;
+    let ended = null;
+    let endedT = null;
+    let lastStepAt = startedAt;
+    let last = null;
+    let lastBeat = 0;
+    const windowNow = () => (wall ? clock() : tapeT);
+    /** Panic, the stop marker and the window; checked on every step and on every heartbeat (a stream can go quiet). */
+    const checkEnd = (panic) => {
+        if (panic && !ended)
+            ended = { state: 'stopped', reason: `the panic switch is engaged (${panic.reason})` };
+        const stop = forwardStopRequested(home, forwardId);
+        if (stop && !ended)
+            ended = { state: 'stopped', reason: `stopped early by ${stop.by}` };
+        const nowT = windowNow();
+        if (!ended && nowT !== null && endsAt !== null && nowT >= endsAt)
+            ended = { state: 'done', reason: `window reached (${t.window.hours} h)` };
+        if (!ended && t.window.trades !== null && closed >= t.window.trades)
+            ended = { state: 'done', reason: `window reached (${closed} closed trades)` };
+        if (ended && endedT === null)
+            endedT = nowT ?? clock();
+    };
+    const beat = (force = false) => {
+        const n = clock();
+        if (!force && n - lastBeat < FORWARD_HEARTBEAT_MS / 2)
+            return;
+        lastBeat = n;
+        const cur = loadForwardTest(home, forwardId) ?? t;
+        t = { ...cur, heartbeatAt: n, endsAt, progress: last ? { closed, open: last.positions.length, equityUsd: last.book.equityUsd, netUsd: last.book.equityUsd - last.book.startUsd, candidates: last.candidates.length } : cur.progress };
+        try {
+            saveForwardTest(home, t);
+        }
+        catch { /* the next beat retries */ }
+    };
+    const timer = setInterval(() => {
+        beat(true);
+        if (!wall)
+            return;
+        checkEnd(o.killSwitch?.engaged() ?? null);
+        // Ended, but no step for a while (a quiet stream): close the stream so the run ends and the report is written.
+        if (ended && clock() - lastStepAt > STALL_MS)
+            o.source?.stop?.();
+    }, FORWARD_HEARTBEAT_MS);
+    timer.unref?.();
+    const safety = () => {
+        const panic = o.killSwitch?.engaged() ?? null;
+        checkEnd(panic);
+        // The window end flattens at the next tick; a bag that cannot sell (no liquidity) ends the stream after a grace.
+        const nowT = windowNow();
+        if (ended && endedT !== null && nowT !== null && nowT - endedT > FLATTEN_GRACE_MS)
+            o.source?.stop?.();
+        if (ended) {
+            return { halt: ended.state === 'done' ? 'forward-window' : panic ? 'kill-switch' : 'forward-stopped', detail: ended.reason, flatten: true, pauseEntries: null, endWhenFlat: true };
+        }
+        return { halt: null, flatten: false, pauseEntries: null, endWhenFlat: false };
+    };
+    let res = null;
+    let error = null;
+    try {
+        res = await runAutotrade({
+            strategy, ...(o.source ? { source: o.source } : { tape: o.tape }), sessions: o.sessions, gate: o.gate, dossier: o.dossier, vet: o.vet, executor: simExecutor(strategy.execution),
+            pacing: o.pacing ?? { mode: 'live' }, ledger, runId, verbose: true, onLine: say, safety,
+            onState: (st) => {
+                if (!wall && tapeT === null && t.window.hours !== null)
+                    endsAt = st.t + t.window.hours * 3_600_000;
+                tapeT = st.t;
+                lastStepAt = clock();
+                last = st;
+                beat();
+            },
+        });
+    }
+    catch (e) {
+        error = e.message.slice(0, 300);
+    }
+    clearInterval(timer);
+    const endedAt = clock();
+    const cur = loadForwardTest(home, forwardId) ?? t;
+    let metrics = null;
+    if (res) {
+        const r = report(strategy, { source: srcName, ticks: [], mints: [] }, res);
+        metrics = metricsOf(r, runFills(res));
+    }
+    // A live stream that ends by itself (the data layer stopped) before the window is an early end, never "done".
+    const fin = error ? { state: 'failed', reason: `the run failed: ${error}` }
+        : ended ? ended : { state: 'stopped', reason: 'the tick stream ended before the window' };
+    t = { ...cur, state: fin.state, endReason: fin.reason, endedAt, endsAt, heartbeatAt: endedAt, metrics, progress: last ? { closed: metrics?.trades ?? closed, open: res?.openAtEnd.length ?? 0, equityUsd: last.book.equityUsd, netUsd: metrics?.netUsd ?? 0, candidates: res?.candidates ?? 0 } : cur.progress };
+    ledger.add(endedAt, 'forward_end', { forwardId, state: fin.state, reason: fin.reason, ...(metrics ? { trades: metrics.trades, netUsd: metrics.netUsd } : {}) });
+    saveForwardTest(home, t);
+    rmSync(forwardStopPath(home, forwardId), { force: true });
+    recordForwardResult(home, resultOf(t));
+    writeForwardSummary(home, t);
+    say(`forward test ${forwardId} ${fin.state}: ${fin.reason}${metrics ? ` · ${metricsLine(metrics)}` : ''} · ledger ${files.ledger}`);
+    return { ok: true, test: t };
+}
+/** The one-line result real mode's arm panel shows (card A reads `summary`). */
+export function writeForwardSummary(home, t) {
+    if (!t.metrics)
+        return;
+    const days = t.startedAt && t.endedAt ? Math.round(((t.endedAt - t.startedAt) / 86_400_000) * 100) / 100 : null;
+    const counted = t.state === 'done' && t.source.startsWith('live');
+    // ASCII only: real mode's arm panel prints this line through a printable-ASCII filter.
+    const summary = `${t.forwardId} ${t.state}${counted ? '' : ' (does not count)'}; v${t.version}; ${t.metrics.trades} trades; net ${usd(t.metrics.netUsd)} (${t.metrics.netPct}%); ${t.source.startsWith('live') ? 'paper, live data' : 'paper, replay'}${t.metrics.trades < 20 ? '; too few trades to claim anything' : ''}`;
+    mkdirSync(forwardRoot(home), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(forwardSummaryPath(home, t.strategyId), { schema: 'dexterm-forward-summary/1', forwardId: t.forwardId, version: t.version, rulesHash: t.rulesHash, state: t.state, counted, summary, trades: t.metrics.trades, netPct: t.metrics.netPct, days });
+}

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

@@ -22,6 +22,10 @@
 // execution-port  where an approved entry goes: the paper port (local single-use proofs) and the live stub (task-1527)
 // chat       Telegram notify, control and approve-to-trade through the user's own bot; chat/ (task-1527)
 // yolo       task-1532: the full-port replay (rugs, loss spread, how often it zeroed the wallet); paper only
+// signal / outbox / signal-channels / receipts / real-mode  task-1645: mode real = the paper engine + a LIVE TRADE FIRE
+//            signal per fill to the user's own executor (webhook, command hook, JSONL, MCP feed, Telegram copy); no key
+// limits / executor-health / report  task-1654: every real-mode limit user-set per scope (stricter wins), executor
+//            heartbeats + the silence pause, the paper-vs-real divergence report and the digest
 //
 // The screener filter grammar is imported by path from the CLI's screener (one parser for the screen and
 // for strategies); nothing in this package touches a key or a wallet, and nothing places a live order (task-1571). The desk executor
@@ -51,3 +55,18 @@ export * from "./trade-ledger.js";
 export * from "./execution-port.js";
 export * from "./chat/index.js";
 export * from "./yolo.js";
+export * from "./signal.js";
+export * from "./outbox.js";
+export * from "./signal-channels.js";
+export * from "./receipts.js";
+export * from "./real-mode.js";
+export * from "./journey.js";
+export * from "./forward.js";
+export * from "./service.js";
+export * from "./service-guard.js";
+export * from "./service-recover.js";
+export * from "./service-install.js";
+export * from "./limits.js";
+export * from "./paper-limits.js";
+export * from "./executor-health.js";
+export * from "./report.js";