opencandle 0.10.0 → 0.11.1

package/src/tools/market/crypto-price.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@sinclair/typebox";
+import { buildFreshnessStamp, type FreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
 import { getCryptoPrice } from "../../providers/coingecko.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
 import type { CryptoPrice } from "../../types/market.js";
@@ -10,7 +11,10 @@ const params = Type.Object({
   }),
 });
 
-export const cryptoPriceTool: AgentTool<typeof params, CryptoPrice> = {
+export const cryptoPriceTool: AgentTool<
+  typeof params,
+  CryptoPrice & { freshness: FreshnessStamp }
+> = {
   name: "get_crypto_price",
   label: "Crypto Price",
   description: "Get current crypto price, 24h change, market cap, volume, ATH, and supply data",
@@ -26,6 +30,13 @@ export const cryptoPriceTool: AgentTool<typeof params, CryptoPrice> = {
       };
     }
     const crypto = result.data;
+    const freshness = buildFreshnessStamp({
+      asOf: crypto.asOf,
+      cached: result.cached,
+      stale: result.stale,
+      cachedAt: result.cached || result.stale ? result.timestamp : undefined,
+      assetClass: "crypto",
+    });
     const sign = crypto.changePercent24h >= 0 ? "+" : "";
     const text = [
       `${crypto.name} (${crypto.symbol.toUpperCase()}): $${formatPrice(crypto.price)} (${sign}${crypto.changePercent24h.toFixed(2)}%)`,
@@ -33,9 +44,10 @@ export const cryptoPriceTool: AgentTool<typeof params, CryptoPrice> = {
       `Market Cap: $${formatLargeNumber(crypto.marketCap)} | 24h Volume: $${formatLargeNumber(crypto.volume24h)}`,
       `ATH: $${formatPrice(crypto.ath)} (${crypto.athDate.split("T")[0]})`,
       `Circulating: ${formatLargeNumber(crypto.circulatingSupply)} ${crypto.symbol.toUpperCase()}`,
+      formatAsOfLine(freshness),
     ].join("\n");
 
-    return { content: [{ type: "text", text }], details: crypto };
+    return { content: [{ type: "text", text }], details: { ...crypto, freshness } };
   },
 };
 

package/src/tools/market/screen-stocks.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { type Static, Type } from "@sinclair/typebox";
+import { buildFreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
 import type { ScreenerRow, ScreenFilterOp } from "../../providers/tradingview.js";
 import { screenStocks } from "../../providers/tradingview.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
@@ -136,12 +137,21 @@ export const screenStocksTool: AgentTool<typeof params, ScreenerRow[]> = {
     }
 
     const rows = result.data;
+    const freshness = buildFreshnessStamp({
+      cached: result.cached,
+      stale: result.stale,
+      cachedAt: result.cached || result.stale ? result.timestamp : undefined,
+      dataDelayMs: 15 * 60_000,
+    });
     if (rows.length === 0) {
       return {
         content: [
           {
             type: "text",
-            text: "No stocks matched the screen. TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.",
+            text: [
+              "No stocks matched the screen. TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.",
+              formatAsOfLine(freshness),
+            ].join("\n"),
           },
         ],
         details: rows,
@@ -150,11 +160,12 @@ export const screenStocksTool: AgentTool<typeof params, ScreenerRow[]> = {
 
     const lines = [
       `**Stock screen** — ${rows.length} TradingView result${rows.length === 1 ? "" : "s"}`,
-      ...(result.stale ? [`⚠ Using cached TradingView screen from ${result.timestamp}.`] : []),
-      `Data freshness: ${result.stale ? `cached screen retrieved at ${result.timestamp}` : `retrieved at ${result.timestamp}`}; TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.`,
+      rows[0]?.dataCaveat ??
+        "TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.",
       formatInterpretationNote(normalized),
       "",
       ...rows.map(formatRow),
+      formatAsOfLine(freshness),
     ];
 
     return {

package/src/tools/market/stock-quote.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@sinclair/typebox";
 import { getConfig } from "../../config.js";
+import { buildFreshnessStamp, type FreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
 import { getGlobalQuote } from "../../providers/alpha-vantage.js";
 import { withFallback } from "../../providers/with-fallback.js";
 import { getQuote } from "../../providers/yahoo-finance.js";
@@ -10,54 +11,59 @@ const params = Type.Object({
   symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, TSLA)" }),
 });
 
-export const stockQuoteTool: AgentTool<typeof params, StockQuote> = {
-  name: "get_stock_quote",
-  label: "Stock Quote",
-  description:
-    "Get real-time stock price, volume, market cap, and 52-week range for a ticker symbol",
-  parameters: params,
-  async execute(_toolCallId, args) {
-    const symbol = args.symbol.toUpperCase();
-    const apiKey = getConfig().alphaVantageApiKey;
+export const stockQuoteTool: AgentTool<typeof params, StockQuote & { freshness: FreshnessStamp }> =
+  {
+    name: "get_stock_quote",
+    label: "Stock Quote",
+    description:
+      "Get real-time stock price, volume, market cap, and 52-week range for a ticker symbol",
+    parameters: params,
+    async execute(_toolCallId, args) {
+      const symbol = args.symbol.toUpperCase();
+      const apiKey = getConfig().alphaVantageApiKey;
 
-    const entries = [
-      { provider: "yahoo" as const, fn: () => getQuote(symbol) },
-      ...(apiKey
-        ? [{ provider: "alphavantage" as const, fn: () => getGlobalQuote(symbol, apiKey) }]
-        : []),
-    ];
+      const entries = [
+        { provider: "yahoo" as const, fn: () => getQuote(symbol) },
+        ...(apiKey
+          ? [{ provider: "alphavantage" as const, fn: () => getGlobalQuote(symbol, apiKey) }]
+          : []),
+      ];
 
-    const result = await withFallback(entries);
-    if (result.status === "unavailable") {
-      return {
-        content: [
-          { type: "text", text: `⚠ Stock quote unavailable for ${symbol} (${result.reason}).` },
-        ],
-        details: null as any,
-      };
-    }
-    const quote = result.data;
-    const sign = quote.changePercent >= 0 ? "+" : "";
+      const result = await withFallback(entries);
+      if (result.status === "unavailable") {
+        return {
+          content: [
+            { type: "text", text: `⚠ Stock quote unavailable for ${symbol} (${result.reason}).` },
+          ],
+          details: null as any,
+        };
+      }
+      const quote = result.data;
+      const freshness = buildFreshnessStamp({
+        asOf: quote.asOf,
+        cached: result.cached,
+        stale: result.stale,
+        cachedAt: result.cached || result.stale ? result.timestamp : undefined,
+      });
+      const sign = quote.changePercent >= 0 ? "+" : "";
 
-    const week52 =
-      quote.week52High > 0 && quote.week52Low > 0
-        ? `$${quote.week52Low.toFixed(2)} - $${quote.week52High.toFixed(2)}`
-        : "N/A";
-    const marketCapStr = quote.marketCap > 0 ? `$${formatLargeNumber(quote.marketCap)}` : "N/A";
+      const week52 =
+        quote.week52High > 0 && quote.week52Low > 0
+          ? `$${quote.week52Low.toFixed(2)} - $${quote.week52High.toFixed(2)}`
+          : "N/A";
+      const marketCapStr = quote.marketCap > 0 ? `$${formatLargeNumber(quote.marketCap)}` : "N/A";
 
-    const text = [
-      `${quote.symbol}: $${quote.price.toFixed(2)} (${sign}${quote.changePercent.toFixed(2)}%)`,
-      `Open: $${quote.open.toFixed(2)} | High: $${quote.high.toFixed(2)} | Low: $${quote.low.toFixed(2)}`,
-      `Volume: ${quote.volume.toLocaleString()} | Market Cap: ${marketCapStr}`,
-      `52W Range: ${week52}`,
-    ].join("\n");
+      const text = [
+        `${quote.symbol}: $${quote.price.toFixed(2)} (${sign}${quote.changePercent.toFixed(2)}%)`,
+        `Open: $${quote.open.toFixed(2)} | High: $${quote.high.toFixed(2)} | Low: $${quote.low.toFixed(2)}`,
+        `Volume: ${quote.volume.toLocaleString()} | Market Cap: ${marketCapStr}`,
+        `52W Range: ${week52}`,
+        formatAsOfLine(freshness),
+      ].join("\n");
 
-    const prefix = result.stale
-      ? `⚠ Using cached quote from ${result.timestamp} (provider rate limited)\n`
-      : "";
-    return { content: [{ type: "text", text: prefix + text }], details: quote };
-  },
-};
+      return { content: [{ type: "text", text }], details: { ...quote, freshness } };
+    },
+  };
 
 function formatLargeNumber(n: number): string {
   if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;

package/src/tools/options/option-chain.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@sinclair/typebox";
+import { buildFreshnessStamp, type FreshnessStamp, formatAsOfLine } from "../../infra/freshness.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
 import { getOptionsChain } from "../../providers/yahoo-finance.js";
 import type { OptionContract, OptionsChain } from "../../types/options.js";
@@ -22,7 +23,10 @@ const params = Type.Object({
   ),
 });
 
-export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
+export const optionChainTool: AgentTool<
+  typeof params,
+  OptionsChain & { freshness: FreshnessStamp }
+> = {
   name: "get_option_chain",
   label: "Options Chain",
   description:
@@ -43,6 +47,12 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
       };
     }
     const chain = result.data;
+    const freshness = buildFreshnessStamp({
+      asOf: chain.asOf,
+      cached: result.cached,
+      stale: result.stale,
+      cachedAt: result.cached || result.stale ? result.timestamp : undefined,
+    });
 
     const lines: string[] = [
       `**${chain.symbol} Options Chain** — Expiry: ${chain.expirationDate}`,
@@ -90,8 +100,12 @@ export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
     }
 
     lines.push(`Put/Call Ratio: ${chain.putCallRatio.toFixed(2)}`);
+    lines.push(formatAsOfLine(freshness));
 
-    return { content: [{ type: "text", text: lines.join("\n") }], details: chain };
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { ...chain, freshness },
+    };
   },
 };
 

package/src/tools/portfolio/daily-report.ts

@@ -1,7 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@sinclair/typebox";
 import {
-  getOrCreateDefaultWatchlistReportTemplate,
+  findDefaultWatchlistReportTemplate,
   nextDailyReportRunAt,
   recordDailyWatchlistReportRun,
   targetsDefaultWatchlist,
@@ -84,14 +84,20 @@ export const dailyReportTool: AgentTool<typeof params> = {
         return { content: [{ type: "text", text: lines.join("\n") }], details: runs };
       }
 
-      const template = getOrCreateDefaultWatchlistReportTemplate(service);
+      // Manual runs link to the configured schedule when one exists but never
+      // create a template as a side effect — generation must not imply a
+      // schedule the user did not set up.
+      const template = findDefaultWatchlistReportTemplate(service);
       const { report, run } = await recordDailyWatchlistReportRun(service, {
-        templateId: template.id,
+        templateId: template?.id ?? null,
         triggerType: "manual",
       });
       await deliverPendingNotifications(service);
+      const text = template
+        ? report.text
+        : `${report.text}\n\n(Unscheduled manual run — use the configure action to set up a morning report that runs while OpenCandle is open.)`;
       return {
-        content: [{ type: "text", text: report.text }],
+        content: [{ type: "text", text }],
         details: run,
       };
     } finally {

package/src/tools/portfolio/risk-analysis.ts

@@ -169,5 +169,5 @@ function riskSummary(m: RiskMetrics): string {
   if (m.sharpeRatio < 0) signals.push("Negative risk-adjusted returns");
   if (m.sharpeRatio >= 1.5) signals.push("Strong risk-adjusted performance");
   if (m.var95 > 0.03) signals.push("High daily VaR (>3%)");
-  return signals.length > 0 ? "Flags: " + signals.join(" | ") : "Risk profile appears moderate";
+  return signals.length > 0 ? `Flags: ${signals.join(" | ")}` : "Risk profile appears moderate";
 }

package/src/tools/technical/backtest.ts

@@ -7,141 +7,165 @@ import { computeRSI, computeSMA } from "./indicators.js";
 
 export type Strategy = "sma_crossover" | "sma_50_200_crossover" | "rsi_mean_reversion";
 
+/** Flat per-side transaction cost assumption, in basis points. */
+export const DEFAULT_COST_BPS = 5;
+
+/** What this simulator deliberately does not model. Rendered in tool output. */
+export const BACKTEST_LIMITATIONS = [
+  "Fills are simulated at the next bar's open after a signal; intrabar moves and gaps beyond that open are not modeled",
+  "Only a flat per-side cost is applied — no slippage model, spreads, or market impact",
+  "Dividends, taxes, and financing costs are excluded",
+  "Liquidity is assumed unlimited at the fill price",
+];
+
+export interface BacktestOptions {
+  /** Flat per-side cost in basis points applied to every fill. */
+  costBps?: number;
+}
+
+export interface BacktestTrade {
+  type: "buy" | "sell";
+  date: string;
+  price: number;
+  pnl?: number;
+  forced?: boolean;
+}
+
 export interface BacktestResult {
   strategy: string;
   totalReturn: number;
   buyAndHoldReturn: number;
   trades: number;
+  forcedClosures: number;
   wins: number;
   winRate: number;
   maxDrawdown: number;
-  tradeLog: Array<{ type: "buy" | "sell"; date: string; price: number; pnl?: number }>;
+  costBpsPerSide: number;
+  /** Signal generated on the final bar that has no next open to fill at. */
+  pendingSignal: { type: "buy" | "sell"; date: string } | null;
+  tradeLog: BacktestTrade[];
 }
 
-export function runBacktest(bars: OHLCV[], strategy: Strategy): BacktestResult {
-  const closes = bars.map((b) => b.close);
+type Signal = "enter" | "exit" | null;
 
-  if (strategy === "sma_crossover") {
-    return backtestSMACrossover(bars, closes, 20, 50, strategy);
+export function runBacktest(
+  bars: OHLCV[],
+  strategy: Strategy,
+  options?: BacktestOptions,
+): BacktestResult {
+  const closes = bars.map((b) => b.close);
+  const costBps = options?.costBps ?? DEFAULT_COST_BPS;
+
+  if (strategy === "sma_crossover" || strategy === "sma_50_200_crossover") {
+    const [shortWindow, longWindow] = strategy === "sma_crossover" ? [20, 50] : [50, 200];
+    const shortSma = computeSMA(closes, shortWindow);
+    const longSma = computeSMA(closes, longWindow);
+    if (longSma.length === 0) {
+      return emptyResult(strategy, closes, costBps);
+    }
+    const signalAt = (barIdx: number): Signal => {
+      const sShort = shortSma[barIdx - (shortWindow - 1)];
+      const sLong = longSma[barIdx - (longWindow - 1)];
+      if (sShort > sLong) return "enter";
+      if (sShort < sLong) return "exit";
+      return null;
+    };
+    return simulate(bars, closes, signalAt, longWindow - 1, strategy, costBps);
   }
-  if (strategy === "sma_50_200_crossover") {
-    return backtestSMACrossover(bars, closes, 50, 200, strategy);
+
+  const rsi = computeRSI(closes, 14);
+  if (rsi.length === 0) {
+    return emptyResult("rsi_mean_reversion", closes, costBps);
   }
-  return backtestRSIMeanReversion(bars, closes);
+  const rsiOffset = 14;
+  const signalAt = (barIdx: number): Signal => {
+    const r = rsi[barIdx - rsiOffset];
+    if (r < 30) return "enter";
+    if (r > 70) return "exit";
+    return null;
+  };
+  return simulate(bars, closes, signalAt, rsiOffset, "rsi_mean_reversion", costBps);
 }
 
-function backtestSMACrossover(
+// Shared fill engine: a signal computed from bar N's close fills at bar N+1's
+// open (no same-bar lookahead), with a flat per-side cost on every fill. A
+// signal on the final bar is reported as pending instead of a phantom trade.
+function simulate(
   bars: OHLCV[],
   closes: number[],
-  shortWindow: number,
-  longWindow: number,
+  signalAt: (barIdx: number) => Signal,
+  startIdx: number,
   strategyName: Strategy,
+  costBps: number,
 ): BacktestResult {
-  const shortSma = computeSMA(closes, shortWindow);
-  const longSma = computeSMA(closes, longWindow);
-
-  if (longSma.length === 0) {
-    return emptyResult(strategyName, closes);
-  }
-
-  const shortOffset = shortWindow - 1;
-  const longOffset = longWindow - 1;
-
+  const cost = costBps / 10_000;
   let position = false;
-  let entryPrice = 0;
+  let entryFill = 0;
+  let pendingAction: Signal = null;
+  let pendingSignal: BacktestResult["pendingSignal"] = null;
   const tradeLog: BacktestResult["tradeLog"] = [];
   let equity = 1.0;
   let peak = 1.0;
   let maxDd = 0;
 
-  for (let i = 0; i < longSma.length; i++) {
-    const barIdx = i + longOffset;
-    const shortSmaIdx = i + (longOffset - shortOffset);
-    const sShort = shortSma[shortSmaIdx];
-    const sLong = longSma[i];
-    const price = closes[barIdx];
-
-    if (!position && sShort > sLong && price > 0) {
-      // Buy signal
-      position = true;
-      entryPrice = price;
-      tradeLog.push({ type: "buy", date: bars[barIdx].date, price });
-    } else if (position && sShort < sLong) {
-      // Sell signal
-      const pnl = (price - entryPrice) / entryPrice;
-      equity *= 1 + pnl;
-      tradeLog.push({ type: "sell", date: bars[barIdx].date, price, pnl });
-      position = false;
+  for (let i = startIdx; i < bars.length; i++) {
+    // Execute the previous bar's signal at this bar's open.
+    if (pendingAction === "enter" && !position) {
+      const fillPrice = bars[i].open;
+      if (fillPrice > 0) {
+        position = true;
+        entryFill = fillPrice * (1 + cost);
+        tradeLog.push({ type: "buy", date: bars[i].date, price: fillPrice });
+      }
+    } else if (pendingAction === "exit" && position) {
+      const fillPrice = bars[i].open;
+      if (fillPrice > 0 && entryFill > 0) {
+        const pnl = (fillPrice * (1 - cost) - entryFill) / entryFill;
+        equity *= 1 + pnl;
+        tradeLog.push({ type: "sell", date: bars[i].date, price: fillPrice, pnl });
+        position = false;
+      }
+    }
+    pendingAction = null;
+
+    // Evaluate the signal at this bar's close.
+    const signal = signalAt(i);
+    if ((signal === "enter" && !position) || (signal === "exit" && position)) {
+      if (i + 1 >= bars.length) {
+        pendingSignal = { type: signal === "enter" ? "buy" : "sell", date: bars[i].date };
+      } else {
+        pendingAction = signal;
+      }
     }
 
-    // Track mark-to-market equity for accurate drawdown
-    const currentEquity = position ? equity * (1 + (price - entryPrice) / entryPrice) : equity;
+    // Track mark-to-market equity for accurate drawdown.
+    const price = closes[i];
+    const currentEquity =
+      position && entryFill > 0 && price > 0
+        ? equity * (1 + (price - entryFill) / entryFill)
+        : equity;
     if (currentEquity > peak) peak = currentEquity;
     const dd = (peak - currentEquity) / peak;
     if (dd > maxDd) maxDd = dd;
   }
 
-  // Close open position at end
-  if (position) {
+  // Close any open position at the final close for reporting.
+  if (position && entryFill > 0) {
     const lastPrice = closes[closes.length - 1];
-    const pnl = (lastPrice - entryPrice) / entryPrice;
-    equity *= 1 + pnl;
-    tradeLog.push({ type: "sell", date: bars[bars.length - 1].date, price: lastPrice, pnl });
-  }
-
-  return buildResult(strategyName, equity - 1, closes, tradeLog, maxDd);
-}
-
-function backtestRSIMeanReversion(bars: OHLCV[], closes: number[]): BacktestResult {
-  const rsi = computeRSI(closes, 14);
-
-  if (rsi.length === 0) {
-    return emptyResult("rsi_mean_reversion", closes);
-  }
-
-  // RSI starts at index 14 (after 14 periods of data)
-  const rsiOffset = 14;
-  let position = false;
-  let entryPrice = 0;
-  const tradeLog: BacktestResult["tradeLog"] = [];
-  let equity = 1.0;
-  let peak = 1.0;
-  let maxDd = 0;
-
-  for (let i = 0; i < rsi.length; i++) {
-    const barIdx = i + rsiOffset;
-    const r = rsi[i];
-    const price = closes[barIdx];
-
-    if (!position && r < 30 && price > 0) {
-      // RSI oversold → buy
-      position = true;
-      entryPrice = price;
-      tradeLog.push({ type: "buy", date: bars[barIdx].date, price });
-    } else if (position && r > 70) {
-      // RSI overbought → sell
-      const pnl = (price - entryPrice) / entryPrice;
+    if (lastPrice > 0) {
+      const pnl = (lastPrice * (1 - cost) - entryFill) / entryFill;
       equity *= 1 + pnl;
-      tradeLog.push({ type: "sell", date: bars[barIdx].date, price, pnl });
-      position = false;
+      tradeLog.push({
+        type: "sell",
+        date: bars[bars.length - 1].date,
+        price: lastPrice,
+        pnl,
+        forced: true,
+      });
     }
-
-    // Track mark-to-market equity for accurate drawdown
-    const currentEquity = position ? equity * (1 + (price - entryPrice) / entryPrice) : equity;
-    if (currentEquity > peak) peak = currentEquity;
-    const dd = (peak - currentEquity) / peak;
-    if (dd > maxDd) maxDd = dd;
-  }
-
-  // Close open position at end
-  if (position) {
-    const lastPrice = closes[closes.length - 1];
-    const pnl = (lastPrice - entryPrice) / entryPrice;
-    equity *= 1 + pnl;
-    tradeLog.push({ type: "sell", date: bars[bars.length - 1].date, price: lastPrice, pnl });
   }
 
-  return buildResult("rsi_mean_reversion", equity - 1, closes, tradeLog, maxDd);
+  return buildResult(strategyName, equity - 1, closes, tradeLog, maxDd, costBps, pendingSignal);
 }
 
 function buildResult(
@@ -150,9 +174,15 @@ function buildResult(
   closes: number[],
   tradeLog: BacktestResult["tradeLog"],
   maxDrawdown: number,
+  costBpsPerSide: number,
+  pendingSignal: BacktestResult["pendingSignal"],
 ): BacktestResult {
-  const sellTrades = tradeLog.filter((t) => t.type === "sell" && t.pnl != null);
-  const wins = sellTrades.filter((t) => t.pnl! > 0).length;
+  const sellTrades = tradeLog.filter(
+    (t): t is BacktestTrade & { type: "sell"; pnl: number } =>
+      t.type === "sell" && t.pnl != null && !t.forced,
+  );
+  const forcedClosures = tradeLog.filter((t) => t.type === "sell" && t.forced).length;
+  const wins = sellTrades.filter((t) => t.pnl > 0).length;
   const buyAndHoldReturn =
     closes.length > 1 && closes[0] > 0 ? (closes[closes.length - 1] - closes[0]) / closes[0] : 0;
 
@@ -161,23 +191,29 @@ function buildResult(
     totalReturn,
     buyAndHoldReturn,
     trades: sellTrades.length,
+    forcedClosures,
     wins,
     winRate: sellTrades.length > 0 ? wins / sellTrades.length : 0,
     maxDrawdown,
+    costBpsPerSide,
+    pendingSignal,
     tradeLog,
   };
 }
 
-function emptyResult(strategy: string, closes: number[]): BacktestResult {
+function emptyResult(strategy: string, closes: number[], costBpsPerSide: number): BacktestResult {
   return {
     strategy,
     totalReturn: 0,
     buyAndHoldReturn:
       closes.length > 1 && closes[0] > 0 ? (closes[closes.length - 1] - closes[0]) / closes[0] : 0,
     trades: 0,
+    forcedClosures: 0,
     wins: 0,
     winRate: 0,
     maxDrawdown: 0,
+    costBpsPerSide,
+    pendingSignal: null,
     tradeLog: [],
   };
 }
@@ -200,13 +236,20 @@ const params = Type.Object({
       description: "Historical period to backtest: 1y, 2y, 5y. Default: 2y",
     }),
   ),
+  cost_bps: Type.Optional(
+    Type.Number({
+      minimum: 0,
+      maximum: 100,
+      description: `Flat per-side transaction cost in basis points applied to every fill. Default: ${DEFAULT_COST_BPS}`,
+    }),
+  ),
 });
 
 export const backtestTool: AgentTool<typeof params> = {
   name: "backtest_strategy",
   label: "Backtest Strategy",
   description:
-    "Backtest a simple trading strategy against historical data. Supported strategies: SMA crossover (SMA20/SMA50), standard long-term SMA crossover (SMA50/SMA200), and RSI mean-reversion (buy <30, sell >70). Returns total return, win rate, max drawdown, and comparison to buy-and-hold.",
+    "Replay a simple trading strategy against historical daily bars. Signals fill at the next bar's open with a flat per-side cost assumption; dividends, taxes, slippage beyond that cost, and liquidity are not modeled. Supported strategies: SMA crossover (SMA20/SMA50), standard long-term SMA crossover (SMA50/SMA200), and RSI mean-reversion (buy <30, sell >70). Returns total return, win rate, max drawdown, and comparison to buy-and-hold.",
   parameters: params,
   async execute(_toolCallId, args) {
     const symbol = args.symbol.toUpperCase();
@@ -235,22 +278,38 @@ export const backtestTool: AgentTool<typeof params> = {
       };
     }
 
-    const result = runBacktest(bars, args.strategy);
+    const costBps = args.cost_bps ?? DEFAULT_COST_BPS;
+    const result = runBacktest(bars, args.strategy, { costBps });
 
     const outperformance = result.totalReturn - result.buyAndHoldReturn;
     const lines = [
       `**${symbol} Backtest: ${strategyLabel(args.strategy)}** (${bars[0].date} to ${bars[bars.length - 1].date}, ${bars.length} days)`,
       ``,
-      `Strategy Return: ${(result.totalReturn * 100).toFixed(2)}%`,
-      `Buy & Hold Return: ${(result.buyAndHoldReturn * 100).toFixed(2)}%`,
+      `Strategy Return (net of costs): ${(result.totalReturn * 100).toFixed(2)}%`,
+      `Buy & Hold Return (gross): ${(result.buyAndHoldReturn * 100).toFixed(2)}%`,
       `Outperformance: ${outperformance >= 0 ? "+" : ""}${(outperformance * 100).toFixed(2)}%`,
       ``,
-      `Trades: ${result.trades} | Wins: ${result.wins} | Win Rate: ${(result.winRate * 100).toFixed(0)}%`,
+      `Signal Trades: ${result.trades} | Forced Closures: ${result.forcedClosures} | Wins: ${result.wins} | Win Rate: ${(result.winRate * 100).toFixed(0)}%`,
       `Max Drawdown: ${(result.maxDrawdown * 100).toFixed(2)}%`,
       ``,
+      `Execution assumptions: signals fill at the next bar's open with a flat cost of ${costBps} bps per side.`,
+      ...(result.pendingSignal
+        ? [
+            `Note: a ${result.pendingSignal.type} signal fired on the final bar (${result.pendingSignal.date}) and is pending — it has no next open to fill at and is not counted as a signal trade.`,
+          ]
+        : []),
+      ...(result.forcedClosures > 0
+        ? [
+            `Note: ${result.forcedClosures} open position${result.forcedClosures === 1 ? " was" : "s were"} liquidated at the final close for return reporting; forced closures are not counted as signal trades.`,
+          ]
+        : []),
+      ``,
       result.totalReturn > result.buyAndHoldReturn
-        ? `Strategy outperformed buy-and-hold by ${(outperformance * 100).toFixed(2)}%.`
-        : `Buy-and-hold outperformed the strategy by ${(-outperformance * 100).toFixed(2)}%.`,
+        ? `In this simulation the strategy outperformed buy-and-hold by ${(outperformance * 100).toFixed(2)}%.`
+        : `In this simulation buy-and-hold outperformed the strategy by ${(-outperformance * 100).toFixed(2)}%.`,
+      ``,
+      `Limitations — this is a strategy replay, not an execution simulation:`,
+      ...BACKTEST_LIMITATIONS.map((limit) => `- ${limit}`),
     ];
 
     return {