npm - tradelab - Versions diffs - 1.0.1 → 1.2.0 - Mend

tradelab 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/CHANGELOG.md +112 -0
package/README.md +188 -328
package/bin/tradelab-mcp.js +7 -0
package/bin/tradelab.js +29 -0
package/dist/cjs/data.cjs +149 -26
package/dist/cjs/index.cjs +1917 -1005
package/dist/cjs/live.cjs +536 -25
package/dist/cjs/ta.cjs +339 -0
package/docs/README.md +32 -66
package/docs/api-reference.md +283 -112
package/docs/backtest-engine.md +210 -252
package/docs/data-reporting-cli.md +114 -156
package/docs/examples.md +6 -6
package/docs/live-trading.md +263 -92
package/docs/mcp.md +285 -0
package/docs/research.md +157 -0
package/examples/liveDashboard.js +33 -0
package/examples/llmSignal.js +33 -0
package/examples/mcpLiveTrading.js +77 -0
package/examples/optimize.js +25 -0
package/package.json +26 -4
package/src/engine/asyncSignal.js +28 -0
package/src/engine/backtest.js +13 -1
package/src/engine/backtestAsync.js +27 -0
package/src/engine/backtestTicks.js +13 -2
package/src/engine/barSystemRunner.js +96 -41
package/src/engine/execution.js +39 -0
package/src/engine/grid.js +15 -0
package/src/engine/llmSignal.js +84 -0
package/src/engine/optimize.js +110 -0
package/src/engine/optimizeWorker.js +67 -0
package/src/engine/portfolio.js +4 -1
package/src/engine/walkForward.js +1 -0
package/src/index.js +9 -0
package/src/live/dashboard/server.js +179 -0
package/src/live/engine/liveEngine.js +2 -2
package/src/live/engine/paperEngine.js +5 -0
package/src/live/index.js +3 -0
package/src/live/session.js +402 -0
package/src/mcp/liveTools.js +179 -0
package/src/mcp/schemas.js +167 -0
package/src/mcp/server.js +35 -0
package/src/mcp/tools.js +265 -0
package/src/metrics/annualize.js +32 -0
package/src/metrics/benchmark.js +55 -0
package/src/metrics/buildMetrics.js +34 -13
package/src/metrics/finite.js +17 -0
package/src/research/combinations.js +18 -0
package/src/research/cpcv.js +47 -0
package/src/research/deflatedSharpe.js +35 -0
package/src/research/index.js +6 -0
package/src/research/monteCarlo.js +88 -0
package/src/research/pbo.js +69 -0
package/src/research/stats.js +78 -0
package/src/strategies/builtins.js +96 -0
package/src/strategies/index.js +30 -0
package/src/ta/channels.js +67 -0
package/src/ta/index.js +16 -0
package/src/ta/oscillators.js +70 -0
package/src/ta/trend.js +78 -0
package/src/utils/random.js +33 -0
package/templates/dashboard.html +661 -0
package/types/index.d.ts +179 -0
package/types/live.d.ts +114 -0
package/types/mcp.d.ts +17 -0
package/types/ta.d.ts +45 -0

package/src/engine/portfolio.js CHANGED Viewed

@@ -148,6 +148,7 @@ function forceExitAll(runners, time) {
 export function backtestPortfolio({
   systems = [],
   equity = 10_000,
+  interval,
   allocation = "equal",
   collectEqSeries = true,
   collectReplay = false,
@@ -307,6 +308,7 @@ export function backtestPortfolio({
   const replay = combineReplay(systemResults, eqSeries, collectReplay);
   const allCandles = systems.flatMap((system) => system.candles || []);
   const orderedCandles = [...allCandles].sort((left, right) => left.time - right.time);
+  const metricsInterval = interval ?? systems[0]?.interval;
   const metrics = buildMetrics({
     closed: trades,
     equityStart: equity,
@@ -314,11 +316,12 @@ export function backtestPortfolio({
     candles: orderedCandles,
     estBarMs: estimateBarMs(orderedCandles),
     eqSeries,
+    interval: metricsInterval,
   });
   return {
     symbol: "PORTFOLIO",
-    interval: undefined,
+    interval: metricsInterval,
     range: undefined,
     trades,
     positions,

package/src/engine/walkForward.js CHANGED Viewed

@@ -225,6 +225,7 @@ export function walkForwardOptimize({
     candles,
     estBarMs: estimateBarMs(candles),
     eqSeries,
+    interval: backtestOptions.interval,
   });
   const bestParamsSummary = summarizeBestParams(windows);

package/src/index.js CHANGED Viewed

@@ -1,9 +1,18 @@
 export { backtest } from "./engine/backtest.js";
+export { backtestAsync } from "./engine/backtestAsync.js";
 export { backtestTicks } from "./engine/backtestTicks.js";
 export { backtestPortfolio } from "./engine/portfolio.js";
+export { LlmSignal } from "./engine/llmSignal.js";
 export { walkForwardOptimize } from "./engine/walkForward.js";
+export { optimize } from "./engine/optimize.js";
+export { grid } from "./engine/grid.js";
+export { listStrategies, getStrategy, registerStrategy } from "./strategies/index.js";
+export * as research from "./research/index.js";
 export { buildMetrics } from "./metrics/buildMetrics.js";
+export { benchmarkStats } from "./metrics/benchmark.js";
+export { clampFinite, BIG_NUMBER } from "./metrics/finite.js";
+export { periodsPerYear } from "./metrics/annualize.js";
 export {
   backtestHistorical,
   cachedCandlesPath,

package/src/live/dashboard/server.js ADDED Viewed

@@ -0,0 +1,179 @@
+import http from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const FALLBACK_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>tradelab live</title>
+  </head>
+  <body>
+    <h1>tradelab live</h1>
+    <pre id="state"></pre>
+    <script>
+      fetch("/state")
+        .then((res) => res.json())
+        .then((state) => {
+          document.getElementById("state").textContent = JSON.stringify(state, null, 2);
+        });
+    </script>
+  </body>
+</html>`;
+function callerModuleDir() {
+  const stack = new Error().stack || "";
+  const lines = stack.split("\n").slice(1);
+  const match = lines
+    .map((line) => line.match(/(?:\()?(file:\/\/\/[^\s)]+|\/[^\s)]+):\d+:\d+/))
+    .find(Boolean);
+  if (!match) return process.cwd();
+  const filePath = match[1].startsWith("file://") ? fileURLToPath(match[1]) : match[1];
+  return path.dirname(filePath);
+}
+function readDashboardHtml() {
+  const here = callerModuleDir();
+  const candidates = [
+    path.join(here, "..", "..", "..", "templates", "dashboard.html"),
+    path.join(here, "..", "..", "templates", "dashboard.html"),
+    path.join(process.cwd(), "templates", "dashboard.html"),
+  ];
+  const htmlPath = candidates.find((candidate) => existsSync(candidate));
+  if (htmlPath) return readFileSync(htmlPath, "utf8");
+  try {
+    return readFileSync(path.join(process.cwd(), "templates", "dashboard.html"), "utf8");
+  } catch {
+    return FALLBACK_HTML;
+  }
+}
+/**
+ * Local realtime dashboard for a LiveEngine or LiveOrchestrator.
+ *
+ * @param {object} opts
+ * @param {{ eventBus: import("../events.js").EventBus, getStatus: Function }} opts.source
+ * @param {number} [opts.port=4317] 0 picks an ephemeral port for tests
+ * @param {number} [opts.maxBuffer=200] recent events replayed to new clients
+ * @returns {{ start: () => Promise<string>, close: () => Promise<void>, server: http.Server }}
+ */
+export function createDashboardServer({ source, port = 4317, maxBuffer = 200 }) {
+  if (!source?.eventBus || typeof source.eventBus.onAny !== "function") {
+    throw new Error("dashboard source must expose an eventBus with onAny()");
+  }
+  const recent = [];
+  const clients = new Set();
+  const unsubscribe = source.eventBus.onAny(({ event, payload }) => {
+    const msg = { event, payload, t: Date.now() };
+    recent.push(msg);
+    if (recent.length > maxBuffer) recent.shift();
+    const frame = `data: ${JSON.stringify(msg)}\n\n`;
+    for (const res of clients) res.write(frame);
+  });
+  const server = http.createServer(async (req, res) => {
+    const url = (req.url || "/").split("?")[0];
+    if (url === "/") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(readDashboardHtml());
+      return;
+    }
+    if (url === "/state") {
+      if (typeof source.refresh === "function") await source.refresh().catch(() => {});
+      const status = typeof source.getStatus === "function" ? source.getStatus() : {};
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(status));
+      return;
+    }
+    if (url === "/command" && req.method === "POST") {
+      const WHITELIST = {
+        flatten: "flatten",
+        stop: "stop",
+        closePosition: "closePosition",
+        cancelOrder: "cancelOrder",
+      };
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", async () => {
+        let cmd;
+        try {
+          cmd = JSON.parse(body || "{}");
+        } catch {
+          cmd = {};
+        }
+        const method = WHITELIST[cmd.type];
+        if (!method || typeof source[method] !== "function") {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: false, error: `unsupported command "${cmd.type}"` }));
+          return;
+        }
+        try {
+          const arg =
+            cmd.type === "closePosition"
+              ? cmd.symbol
+              : cmd.type === "cancelOrder"
+                ? cmd.orderId
+                : undefined;
+          await source[method](arg);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: true }));
+        } catch (error) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              ok: false,
+              error: error instanceof Error ? error.message : String(error),
+            })
+          );
+        }
+      });
+      return;
+    }
+    if (url === "/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      });
+      res.flushHeaders();
+      for (const msg of recent) res.write(`data: ${JSON.stringify(msg)}\n\n`);
+      clients.add(res);
+      req.on("close", () => clients.delete(res));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("not found");
+  });
+  return {
+    start() {
+      return new Promise((resolve) => {
+        server.listen(port, () => {
+          const address = server.address();
+          const actualPort = typeof address === "object" && address ? address.port : port;
+          resolve(`http://localhost:${actualPort}`);
+        });
+      });
+    },
+    close() {
+      unsubscribe();
+      for (const res of clients) res.end();
+      clients.clear();
+      return new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    },
+    server,
+  };
+}

package/src/live/engine/liveEngine.js CHANGED Viewed

@@ -2,7 +2,7 @@ import { calculatePositionSize } from "../../utils/positionSizing.js";
 import { normalizeCandles } from "../../data/csv.js";
 import { isEODBar, ocoExitCheck } from "../../engine/execution.js";
 import {
-  callSignalWithContext,
+  callSignalWithContextAsync,
   normalizeSignal,
   snapshotOpenPosition,
 } from "../../engine/barSystemRunner.js";
@@ -513,7 +513,7 @@ export class LiveEngine {
     if (!this.openPosition && !this.pendingOrder) {
       const context = this._signalContext(bar);
-      const rawSignal = callSignalWithContext({
+      const rawSignal = await callSignalWithContextAsync({
         signal: this.options.signal,
         context,
         index: context.index,

package/src/live/engine/paperEngine.js CHANGED Viewed

@@ -424,6 +424,11 @@ export class PaperEngine extends BrokerAdapter {
     const orders = [...this.openOrders.values()].filter((order) => order.symbol === symbol);
     for (const order of orders) {
+      // Skip orders already consumed this pass (e.g. an OCO sibling about to be
+      // canceled, or any order removed by a prior fill). _fillOrder deletes from
+      // openOrders before emitting, so this guard prevents bracket double-fills
+      // when one bar straddles both stop and target.
+      if (!this.openOrders.has(order.orderId)) continue;
       if (order.type === "limit") {
         if (this._touchesLimit(order, normalizedBar)) {
           this._fillOrder(order, order.limitPrice, "limit", normalizedBar.time);

package/src/live/index.js CHANGED Viewed

@@ -25,3 +25,6 @@ export { PaperEngine, createPaperEngine } from "./engine/paperEngine.js";
 export { LiveEngine, createLiveEngine } from "./engine/liveEngine.js";
 export { LiveOrchestrator, createLiveOrchestrator } from "./orchestrator.js";
+export { createDashboardServer } from "./dashboard/server.js";
+export { TradingSession, SessionManager, createSessionManager } from "./session.js";

package/src/live/session.js ADDED Viewed

@@ -0,0 +1,402 @@
+import { EventBus } from "./events.js";
+import { RiskManager } from "./engine/riskManager.js";
+import { calculatePositionSize } from "../utils/positionSizing.js";
+import { roundStep } from "../engine/execution.js";
+import { PaperEngine } from "./engine/paperEngine.js";
+function oppositeSide(side) {
+  return side === "long" || side === "buy" ? "sell" : "buy";
+}
+function toBrokerSide(side) {
+  return side === "long" || side === "buy" ? "buy" : "sell";
+}
+export class TradingSession {
+  constructor({
+    id,
+    symbol,
+    interval = "1m",
+    broker,
+    mode = "paper",
+    equity = 10_000,
+    riskPct = 1,
+    maxDailyLossPct = 0,
+    maxPositionPct = 1,
+    qtyStep = 0.001,
+    minQty = 0.001,
+    maxLeverage = 2,
+    confirmLive = false,
+    eventBus,
+  } = {}) {
+    if (mode === "live" && (!TradingSession.liveAllowed() || !confirmLive)) {
+      throw new Error(
+        "live trading is gated: set TRADELAB_ALLOW_LIVE=true and pass confirmLive:true with a credentialed broker"
+      );
+    }
+    if (!broker) throw new Error("TradingSession requires a broker (PaperEngine by default)");
+    if (!symbol) throw new Error("TradingSession requires a symbol");
+    this.id = id || `${symbol}-${interval}`;
+    this.symbol = symbol;
+    this.interval = interval;
+    this.broker = broker;
+    this.mode = mode;
+    this.equity = equity;
+    this._startEquity = equity;
+    this.riskPct = riskPct;
+    this.maxPositionPct = maxPositionPct;
+    this.qtyStep = qtyStep;
+    this.minQty = minQty;
+    this.maxLeverage = maxLeverage;
+    this.eventBus = eventBus || new EventBus();
+    this.riskManager = new RiskManager({ maxDailyLossPct, maxDrawdownPct: 0 });
+    this.lastPrice = null;
+    this.running = false;
+    this.events = [];
+    this.brackets = new Map(); // symbol -> { stopId, targetId }
+    this._pendingBracket = null;
+    this._cachedPositions = [];
+    this._cachedOpenOrders = [];
+    this.candleBuffer = [];
+    this._strategy = null;
+    this._wireBrokerEvents();
+  }
+  static liveAllowed() {
+    return process.env.TRADELAB_ALLOW_LIVE === "true";
+  }
+  _record(event, payload) {
+    const msg = { event, payload, t: Date.now() };
+    this.events.push(msg);
+    if (this.events.length > 500) this.events.shift();
+    this.eventBus.emitEvent(event, { sessionId: this.id, symbol: this.symbol, ...payload });
+  }
+  _wireBrokerEvents() {
+    // Forward broker fills/cancels onto the session bus, and run OCO bracket logic.
+    this.broker.on?.("order:filled", (order) => this._onBrokerFillSync(order));
+    this.broker.on?.("order:submitted", (order) => this._record("order:submitted", order));
+    this.broker.on?.("order:canceled", (order) => this._record("order:canceled", order));
+    this.broker.on?.("equity:update", (acct) => this._record("equity:update", acct));
+  }
+  // Sync event handler — fire-and-forget async OCO work via a stored promise
+  _onBrokerFillSync(order) {
+    this._record("order:filled", order);
+    // Resting entry order (e.g. a limit) just filled — attach its staged bracket.
+    if (this._pendingBracket && String(order.clientOrderId || "").includes("-entry-")) {
+      const staged = this._pendingBracket;
+      this._pendingBracket = null;
+      // simulateBar may still be iterating orders, so schedule attach without awaiting.
+      this._pendingCancelPromise = Promise.resolve(
+        this._attachBracket({ ...staged, receipt: order })
+      );
+      return;
+    }
+    // Track bracket leg fills for OCO
+    const bracket = this.brackets.get(this.symbol);
+    if (bracket && (order.orderId === bracket.stopId || order.orderId === bracket.targetId)) {
+      const siblingId = order.orderId === bracket.stopId ? bracket.targetId : bracket.stopId;
+      // Schedule the cancel — simulateBar is still iterating orders, so we must not await here.
+      // We keep a pending cancel promise that refresh() awaits.
+      this._pendingCancelPromise = (async () => {
+        if (siblingId) await this.broker.cancelOrder(siblingId).catch(() => {});
+        this.brackets.delete(this.symbol);
+        this._record("position:closed", { reason: order.orderId === bracket.stopId ? "SL" : "TP" });
+      })();
+    }
+  }
+  async start() {
+    if (!this.broker.isConnected?.()) await this.broker.connect?.({});
+    const acct = await this.broker.getAccount?.().catch(() => null);
+    if (Number.isFinite(acct?.equity)) {
+      this.equity = acct.equity;
+      this._startEquity = acct.equity;
+    }
+    this.riskManager.initialize(this.equity, Date.now());
+    this.running = true;
+    this._record("connected", { mode: this.mode });
+  }
+  async stop({ flatten = false } = {}) {
+    if (flatten) await this.flatten();
+    this.running = false;
+    this._record("shutdown", {});
+  }
+  async pushBar(b) {
+    this.lastPrice = b.close;
+    if (typeof this.broker.simulateBar === "function") {
+      await this.broker.simulateBar(this.symbol, this.interval, b);
+    }
+    // Wait for any pending OCO cancel triggered by simulateBar fills
+    if (this._pendingCancelPromise) {
+      await this._pendingCancelPromise;
+      this._pendingCancelPromise = null;
+    }
+    this.candleBuffer.push(b);
+    if (this.candleBuffer.length > 200) this.candleBuffer.shift();
+    this._record("bar", { close: b.close, time: b.time });
+    await this._syncEquityAndRisk();
+    await this.refresh();
+  }
+  _riskHalted() {
+    const state = this.riskManager.getState?.() || {};
+    return Boolean(state.halted);
+  }
+  async placeOrder({ side, type = "market", qty, riskPct, stop, target, rr, limitPrice } = {}) {
+    if (!this.running) throw new Error("session not started");
+    if (this._riskHalted()) throw new Error("session is risk-halted for the day");
+    const entryRef = type === "limit" ? limitPrice : this.lastPrice;
+    if (!Number.isFinite(entryRef)) throw new Error("no price available; pushBar() a price first");
+    let size = qty;
+    if (!Number.isFinite(size)) {
+      const fraction = Number.isFinite(riskPct) ? riskPct / 100 : this.riskPct / 100;
+      if (!Number.isFinite(stop)) throw new Error("risk-based sizing requires a stop");
+      size = calculatePositionSize({
+        equity: this.equity,
+        entry: entryRef,
+        stop,
+        riskFraction: fraction,
+        qtyStep: this.qtyStep,
+        minQty: this.minQty,
+        maxLeverage: this.maxLeverage,
+      });
+    }
+    size = roundStep(size, this.qtyStep);
+    if (!(size >= this.minQty)) throw new Error(`sized below minQty (${size})`);
+    const receipt = await this.broker.submitOrder({
+      symbol: this.symbol,
+      side: toBrokerSide(side),
+      type,
+      qty: size,
+      limitPrice: type === "limit" ? limitPrice : undefined,
+      clientOrderId: `${this.id}-entry-${Date.now()}`,
+    });
+    // Stage bracket if needed — market orders fill synchronously in PaperEngine
+    if (Number.isFinite(stop) || Number.isFinite(target) || Number.isFinite(rr)) {
+      if (receipt.status === "filled") {
+        await this._attachBracket({ side, size, stop, target, rr, entryRef, receipt });
+      } else {
+        this._pendingBracket = { side, size, stop, target, rr, entryRef };
+      }
+    }
+    await this.refresh();
+    return receipt;
+  }
+  async _attachBracket({ side, size, stop, target, rr, entryRef, receipt }) {
+    const entryFill = receipt?.avgFillPrice ?? entryRef;
+    const risk = Number.isFinite(stop) ? Math.abs(entryFill - stop) : null;
+    const targetPrice = Number.isFinite(target)
+      ? target
+      : Number.isFinite(rr) && risk
+        ? side === "long" || side === "buy"
+          ? entryFill + rr * risk
+          : entryFill - rr * risk
+        : null;
+    const exitSide = oppositeSide(side);
+    const bracket = {};
+    if (Number.isFinite(stop)) {
+      const stopOrder = await this.broker.submitOrder({
+        symbol: this.symbol,
+        side: exitSide,
+        type: "stop",
+        qty: size,
+        stopPrice: stop,
+        clientOrderId: `${this.id}-stop-${Date.now()}`,
+      });
+      bracket.stopId = stopOrder.orderId;
+    }
+    if (Number.isFinite(targetPrice)) {
+      const tgtOrder = await this.broker.submitOrder({
+        symbol: this.symbol,
+        side: exitSide,
+        type: "limit",
+        qty: size,
+        limitPrice: targetPrice,
+        clientOrderId: `${this.id}-target-${Date.now()}`,
+      });
+      bracket.targetId = tgtOrder.orderId;
+    }
+    this.brackets.set(this.symbol, bracket);
+  }
+  async _syncEquityAndRisk() {
+    const acct = await this.broker.getAccount?.().catch(() => null);
+    if (!Number.isFinite(acct?.equity)) return;
+    const prevEquity = this.equity;
+    this.equity = acct.equity;
+    const pnlDelta = this.equity - prevEquity;
+    // Record the trade pnl change so RiskManager can check daily loss
+    if (pnlDelta !== 0) {
+      this.riskManager.recordTrade({ pnl: pnlDelta, timeMs: Date.now(), equity: this.equity });
+    } else {
+      this.riskManager.update({ timeMs: Date.now(), equity: this.equity });
+    }
+  }
+  async closePosition(symbol = this.symbol) {
+    const positions = await this.broker.getPositions();
+    const pos = positions.find((p) => p.symbol === symbol);
+    if (!pos) return null;
+    // cancel any resting bracket first
+    const bracket = this.brackets.get(symbol);
+    if (bracket) {
+      for (const id of [bracket.stopId, bracket.targetId]) {
+        if (id) await this.broker.cancelOrder(id).catch(() => {});
+      }
+      this.brackets.delete(symbol);
+    }
+    const receipt = await this.broker.submitOrder({
+      symbol,
+      side: oppositeSide(pos.side),
+      type: "market",
+      qty: pos.qty,
+      clientOrderId: `${this.id}-close-${Date.now()}`,
+    });
+    await this._syncEquityAndRisk();
+    await this.refresh();
+    return receipt;
+  }
+  async flatten() {
+    const positions = await this.broker.getPositions();
+    for (const p of positions) await this.closePosition(p.symbol);
+    const open = (await this.broker.getOpenOrders?.().catch(() => [])) ?? [];
+    for (const o of open) await this.broker.cancelOrder(o.orderId).catch(() => {});
+    await this.refresh();
+  }
+  async cancelOrder(orderId) {
+    await this.broker.cancelOrder(orderId);
+    await this.refresh();
+  }
+  async getAccount() {
+    return this.broker.getAccount();
+  }
+  async getPositions() {
+    return this.broker.getPositions();
+  }
+  recentEvents(limit = 50) {
+    return this.events.slice(-limit);
+  }
+  getStatus() {
+    const risk = this.riskManager.getState?.() || {};
+    return {
+      id: this.id,
+      symbol: this.symbol,
+      interval: this.interval,
+      mode: this.mode,
+      running: this.running,
+      equity: this.equity,
+      dayPnl: risk.dayPnl ?? 0,
+      lastPrice: this.lastPrice,
+      positions: this._cachedPositions ?? [],
+      openOrders: this._cachedOpenOrders ?? [],
+      risk: { halted: Boolean(risk.halted), ...risk },
+    };
+  }
+  /** Refresh sync caches used by getStatus() */
+  async refresh() {
+    // Wait for any pending OCO cancel before refreshing state
+    if (this._pendingCancelPromise) {
+      await this._pendingCancelPromise;
+      this._pendingCancelPromise = null;
+    }
+    this._cachedPositions = await this.broker.getPositions().catch(() => []);
+    this._cachedOpenOrders = (await this.broker.getOpenOrders?.().catch(() => [])) ?? [];
+    const acct = await this.broker.getAccount?.().catch(() => null);
+    if (Number.isFinite(acct?.equity)) this.equity = acct.equity;
+    return this.getStatus();
+  }
+}
+export class SessionManager {
+  constructor({ brokerFactory } = {}) {
+    this.sessions = new Map();
+    this.brokerFactory = brokerFactory;
+  }
+  async create({
+    id,
+    mode = "paper",
+    symbol,
+    interval = "1m",
+    equity = 10_000,
+    confirmLive = false,
+    broker,
+    ...rest
+  } = {}) {
+    if (this.sessions.has(id)) throw new Error(`session "${id}" already exists`);
+    let resolvedBroker = broker;
+    if (mode === "live") {
+      if (!TradingSession.liveAllowed() || !confirmLive) {
+        throw new Error("live mode requires TRADELAB_ALLOW_LIVE=true and confirmLive:true");
+      }
+      if (!resolvedBroker && this.brokerFactory) {
+        resolvedBroker = this.brokerFactory({ symbol, ...rest });
+      }
+      if (!resolvedBroker) throw new Error("live mode requires a credentialed broker");
+    }
+    if (!resolvedBroker) resolvedBroker = new PaperEngine({ equity });
+    const session = new TradingSession({
+      id,
+      symbol,
+      interval,
+      broker: resolvedBroker,
+      mode,
+      equity,
+      confirmLive,
+      ...rest,
+    });
+    await session.start();
+    this.sessions.set(session.id, session);
+    return session;
+  }
+  get(id) {
+    return this.sessions.get(id) ?? null;
+  }
+  list() {
+    return [...this.sessions.values()];
+  }
+  async remove(id, { flatten = true } = {}) {
+    const s = this.sessions.get(id);
+    if (!s) return;
+    await s.stop({ flatten });
+    this.sessions.delete(id);
+  }
+  async haltAll() {
+    for (const s of this.sessions.values()) await s.stop({ flatten: true });
+    // Remove stopped sessions so list() does not retain them and re-runs don't collide.
+    this.sessions.clear();
+  }
+}
+export function createSessionManager(opts) {
+  return new SessionManager(opts);
+}