kalshi-trading-bot-cli 2.1.6 → 2.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kalshi-trading-bot-cli",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "Kalshi Trading Bot CLI - AI-powered prediction market terminal.",
   "license": "MIT",
   "author": "Octagon AI, Inc.",

package/src/backtest/discovery.ts

@@ -1,9 +1,92 @@
 import type { Database } from 'bun:sqlite';
 import { callKalshiApi } from '../tools/kalshi/api.js';
 import type { KalshiMarket } from '../tools/kalshi/types.js';
+import { fetchAllOctagonEvents } from '../scan/octagon-events-api.js';
 
 const CONCURRENCY = 10;
 
+/** Where the backtest universe is sourced from. */
+export type UniverseSource = 'api' | 'local';
+
+export interface UniverseEntry {
+  event_ticker: string;
+  category: string | null;
+}
+
+export interface Universe {
+  events: UniverseEntry[];
+  source: UniverseSource;
+  description: string;
+}
+
+/**
+ * Resolve the backtest universe (the set of events scored).
+ *
+ * `api` (default): paginate Octagon's covered-events list — systematic,
+ * reproducible across machines, doesn't depend on whatever this install
+ * happened to analyze in the past. Uses fetchAllOctagonEvents directly;
+ * we deliberately do NOT pass hasHistory=true because a prior audit showed
+ * that flag silently dropped 373 of 662 events. The pipeline self-filters
+ * downstream: events with no usable snapshot return null from
+ * selectSnapshotByDate and are skipped cheaply.
+ *
+ * `local`: legacy behavior — pull from the local `octagon_reports` log.
+ * Reflects past usage of this machine, not a defined universe. Useful for
+ * offline runs and for comparing against historical backtests.
+ *
+ * KNOWN LIMITATION: the API returns *today's* covered universe, not the
+ * universe as of the entry date. Events dropped from coverage mid-window
+ * vanish from the backtest — survivorship at the universe level. A true
+ * point-in-time universe requires `events?as_of=<date>` upstream.
+ */
+export async function resolveUniverse(
+  db: Database,
+  opts?: { source?: UniverseSource; category?: string },
+): Promise<Universe> {
+  const source = opts?.source ?? 'api';
+  if (source === 'api') {
+    const all = await fetchAllOctagonEvents();
+    let events: UniverseEntry[] = all.map((e) => ({
+      event_ticker: e.event_ticker,
+      category: e.series_category ?? null,
+    }));
+    if (opts?.category) {
+      const needle = opts.category.toLowerCase();
+      events = events.filter((e) => e.category?.toLowerCase().includes(needle));
+    }
+    return {
+      events,
+      source,
+      description: `${events.length} events from Octagon API (systematic universe)`,
+    };
+  }
+  // Legacy local path
+  const { query, params } = buildEventQuery('', opts?.category);
+  const rows = db.query(query).all(params) as Array<{ event_ticker: string; category: string | null }>;
+  return {
+    events: rows.map((r) => ({ event_ticker: r.event_ticker, category: r.category })),
+    source,
+    description: `${rows.length} events from local octagon_reports (NON-SYSTEMATIC — reflects past usage of this machine)`,
+  };
+}
+
+/**
+ * Fetch the Kalshi event payload for each event in the universe, once.
+ * Returns a map keyed by event_ticker. Both discoverSettledMarkets and
+ * discoverOpenMarkets can read from this single map instead of each
+ * re-fetching every event payload — halves the Kalshi call count.
+ */
+export async function fetchEventPayloads(
+  universe: UniverseEntry[],
+): Promise<Map<string, KalshiMarket[]>> {
+  const out = new Map<string, KalshiMarket[]>();
+  await parallelMap(universe, async (entry) => {
+    const markets = await fetchEventMarkets(entry.event_ticker);
+    out.set(entry.event_ticker, markets);
+  }, CONCURRENCY);
+  return out;
+}
+
 export interface SettledMarket {
   ticker: string;
   event_ticker: string;
@@ -103,13 +186,23 @@ export async function parallelMap<T, R>(
  */
 export async function discoverSettledMarkets(
   db: Database,
-  opts?: { category?: string },
+  opts?: {
+    category?: string;
+    /** Pre-resolved universe + payloads (Phase 4 path). When omitted, falls back to the legacy local SQL path. */
+    universe?: Universe;
+    payloads?: Map<string, KalshiMarket[]>;
+  },
 ): Promise<SettledMarket[]> {
-  const { query, params } = buildEventQuery('', opts?.category);
-  const events = db.query(query).all(params) as Array<{ event_ticker: string; category: string | null }>;
+  let events: Array<{ event_ticker: string; category: string | null }>;
+  if (opts?.universe) {
+    events = opts.universe.events;
+  } else {
+    const { query, params } = buildEventQuery('', opts?.category);
+    events = db.query(query).all(params) as Array<{ event_ticker: string; category: string | null }>;
+  }
 
   const batchResults = await parallelMap(events, async ({ event_ticker, category: cat }) => {
-    const markets = await fetchEventMarkets(event_ticker);
+    const markets = opts?.payloads?.get(event_ticker) ?? await fetchEventMarkets(event_ticker);
     const settled: SettledMarket[] = [];
 
     for (const m of markets) {
@@ -137,13 +230,22 @@ export async function discoverSettledMarkets(
  */
 export async function discoverOpenMarkets(
   db: Database,
-  opts?: { category?: string },
+  opts?: {
+    category?: string;
+    universe?: Universe;
+    payloads?: Map<string, KalshiMarket[]>;
+  },
 ): Promise<OpenMarket[]> {
-  const { query: q2, params: p2 } = buildEventQuery('', opts?.category);
-  const events2 = db.query(q2).all(p2) as Array<{ event_ticker: string; category: string | null }>;
+  let events2: Array<{ event_ticker: string; category: string | null }>;
+  if (opts?.universe) {
+    events2 = opts.universe.events;
+  } else {
+    const { query: q2, params: p2 } = buildEventQuery('', opts?.category);
+    events2 = db.query(q2).all(p2) as Array<{ event_ticker: string; category: string | null }>;
+  }
 
   const batchResults = await parallelMap(events2, async ({ event_ticker, category: cat }) => {
-    const markets = await fetchEventMarkets(event_ticker);
+    const markets = opts?.payloads?.get(event_ticker) ?? await fetchEventMarkets(event_ticker);
     const open: OpenMarket[] = [];
 
     for (const m of markets) {

package/src/backtest/metrics.ts

@@ -1,4 +1,4 @@
-import type { ScoredSignal, BacktestResult } from './types.js';
+import type { ScoredSignal, BacktestResult, LegMetrics } from './types.js';
 
 /**
  * Skill score: how much better Octagon is vs the market as a forecaster.
@@ -44,6 +44,68 @@ export function bootstrapCI(
   return [stats[lo], stats[hi]];
 }
 
+/**
+ * Cluster bootstrap — resamples GROUPS with replacement, not individual rows.
+ *
+ * Use when the unit of risk is the group, not the row. In our case Kalshi
+ * events are multi-outcome: a single "Will the Fed cut N times?" event has
+ * a ladder of NO contracts that all settle together. If the model bets NO
+ * on five rungs and the Fed cuts once, all five settle NO simultaneously
+ * — that's *one* underlying outcome contributing five rows.
+ *
+ * Row-level bootstrap (`bootstrapCI` above) treats those rows as independent
+ * → CI width shrinks with √N where N is the row count. Real effective N is
+ * closer to the event count, so the honest interval is roughly 2× wider.
+ *
+ * This function takes `groups` (each group = a contiguous block of indices
+ * referring to per-row data carried in closures by `statFn`), draws
+ * `groups.length` groups with replacement per iteration, concatenates the
+ * indices, and applies `statFn` to the pooled sample.
+ */
+export function clusterBootstrapCI(
+  groups: number[][],
+  statFn: (sampleIndices: number[]) => number,
+  iterations = 10_000,
+  alpha = 0.05,
+): [number, number] {
+  if (groups.length === 0) return [0, 0];
+  if (!Number.isFinite(iterations) || !Number.isInteger(iterations) || iterations <= 0) {
+    throw new Error(`clusterBootstrapCI: iterations must be a finite integer > 0, got ${iterations}`);
+  }
+  if (!Number.isFinite(alpha) || alpha <= 0 || alpha >= 1) {
+    throw new Error(`clusterBootstrapCI: alpha must be a finite number in (0, 1), got ${alpha}`);
+  }
+  const stats: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const pooled: number[] = [];
+    for (let j = 0; j < groups.length; j++) {
+      const g = groups[Math.floor(Math.random() * groups.length)];
+      pooled.push(...g);
+    }
+    if (pooled.length === 0) { stats.push(0); continue; }
+    stats.push(statFn(pooled));
+  }
+  stats.sort((a, b) => a - b);
+  const lo = Math.min(Math.max(0, Math.floor((alpha / 2) * stats.length)), stats.length - 1);
+  const hi = Math.min(Math.max(0, Math.floor((1 - alpha / 2) * stats.length)), stats.length - 1);
+  return [stats[lo], stats[hi]];
+}
+
+/**
+ * Build event-clustered groups: indices for each signal grouped by event_ticker.
+ * Used to feed clusterBootstrapCI when the underlying signals are correlated
+ * within an event (multi-outcome ladders, mutually-exclusive option sets).
+ */
+function groupIndicesByEvent<T extends { event_ticker: string }>(items: T[]): number[][] {
+  const byEvent = new Map<string, number[]>();
+  items.forEach((item, idx) => {
+    const arr = byEvent.get(item.event_ticker) ?? [];
+    arr.push(idx);
+    byEvent.set(item.event_ticker, arr);
+  });
+  return [...byEvent.values()];
+}
+
 /**
  * Compute Brier score: ((forecast/100) - (outcome/100))²
  * Both forecast and outcome are on 0-100 scale.
@@ -52,10 +114,162 @@ function brier(forecast: number, outcome: number): number {
   return ((forecast / 100) - (outcome / 100)) ** 2;
 }
 
+/** Entry-price bands used by the within-band skill calculation. */
+const PRICE_BANDS: Array<{ label: string; lo: number; hi: number }> = [
+  { label: '5-20¢',   lo: 5,  hi: 20 },
+  { label: '20-40¢',  lo: 20, hi: 40 },
+  { label: '40-60¢',  lo: 40, hi: 60 },
+  { label: '60-80¢',  lo: 60, hi: 80 },
+  { label: '80-95¢',  lo: 80, hi: 95 },
+];
+
+/**
+ * Compute zero-skill baselines on the same post-filter universe as the model.
+ *
+ * Why: Kalshi events are multi-outcome — most resolved contracts settle NO
+ * because each event has one YES outcome and many NOs. A model that
+ * consistently picks NO will hit ~75% by structure alone. The "always-NO"
+ * baseline strips that structural tilt out so we can see whether the model
+ * has any selection skill beyond the universe's bias.
+ *
+ * Within-band skill: model NO-bet ROI minus always-NO ROI, computed inside
+ * entry-price buckets and capital-weighted across buckets. This also
+ * controls for the entry-price mix — a model that only bets cheap
+ * longshots will look great vs. an always-NO baseline run over the full
+ * universe, but mediocre once we compare within the same price band.
+ */
+function computeBaselines(signals: ScoredSignal[]): BacktestResult['baselines'] {
+  // Universe-wide always-NO / always-YES on the same post-filter rows.
+  const noPnl = (s: ScoredSignal): { pnl: number; capital: number; hit: boolean } => {
+    const capital = (100 - s.market_then) / 100;
+    const settlement = 100 - s.market_now;
+    const pnl = (settlement - (100 - s.market_then)) / 100;
+    return { pnl, capital, hit: s.market_now < s.market_then };
+  };
+  const yesPnl = (s: ScoredSignal): { pnl: number; capital: number; hit: boolean } => {
+    const capital = s.market_then / 100;
+    const pnl = (s.market_now - s.market_then) / 100;
+    return { pnl, capital, hit: s.market_now > s.market_then };
+  };
+
+  let noP = 0, noC = 0, noHits = 0;
+  let yesP = 0, yesC = 0, yesHits = 0;
+  for (const s of signals) {
+    const n = noPnl(s); noP += n.pnl; noC += n.capital; if (n.hit) noHits++;
+    const y = yesPnl(s); yesP += y.pnl; yesC += y.capital; if (y.hit) yesHits++;
+  }
+  const alwaysNoRoi = noC > 0 ? noP / noC : 0;
+  const alwaysYesRoi = yesC > 0 ? yesP / yesC : 0;
+  const alwaysNoHitRate = signals.length > 0 ? noHits / signals.length : 0;
+  const alwaysYesHitRate = signals.length > 0 ? yesHits / signals.length : 0;
+
+  // Within-band: bucket by entry price, compute model-NO-bet ROI minus
+  // always-NO ROI per band, then capital-weight the deltas across bands.
+  // The model's NO bets are the meaningful comparable population (the
+  // structural NO tilt is the dominant source of "skill" in the universe).
+  const breakdown: BacktestResult['baselines']['within_band_breakdown'] = [];
+  let weightedDeltaNumer = 0;
+  let weightedDeltaDenom = 0;
+  for (const band of PRICE_BANDS) {
+    const inBand = signals.filter((s) => s.market_then >= band.lo && s.market_then < band.hi);
+    if (inBand.length === 0) continue;
+
+    let bandModelPnl = 0, bandModelCap = 0, bandModelN = 0;
+    let bandNoPnl = 0, bandNoCap = 0;
+    for (const s of inBand) {
+      const n = noPnl(s); bandNoPnl += n.pnl; bandNoCap += n.capital;
+      // Model "bet" here = signal where model picked NO (edge_pp < 0) and
+      // capital is the NO-side capital we already stored in s.capital.
+      if (s.edge_pp < 0) {
+        bandModelPnl += s.pnl;
+        bandModelCap += s.capital;
+        bandModelN++;
+      }
+    }
+    const modelRoi = bandModelCap > 0 ? bandModelPnl / bandModelCap : 0;
+    const baselineRoi = bandNoCap > 0 ? bandNoPnl / bandNoCap : 0;
+    const deltaPp = (modelRoi - baselineRoi) * 100;
+    breakdown.push({
+      band: band.label,
+      model_no_roi: modelRoi,
+      always_no_roi: baselineRoi,
+      skill_delta_pp: deltaPp,
+      n_model: bandModelN,
+      n_universe: inBand.length,
+    });
+    weightedDeltaNumer += deltaPp * bandModelCap;
+    weightedDeltaDenom += bandModelCap;
+  }
+  const withinBandSkillPp = weightedDeltaDenom > 0 ? weightedDeltaNumer / weightedDeltaDenom : 0;
+
+  return {
+    always_no_roi: alwaysNoRoi,
+    always_no_hit_rate: alwaysNoHitRate,
+    always_yes_roi: alwaysYesRoi,
+    always_yes_hit_rate: alwaysYesHitRate,
+    within_band_skill_pp: withinBandSkillPp,
+    within_band_breakdown: breakdown,
+  };
+}
+
+/**
+ * Compute the scorecard for one leg (resolved-only or unresolved-only).
+ * Same hit-rate and capital-weighted ROI definitions as the blended
+ * computation, just scoped to the subset.
+ */
+function computeLegMetrics(signals: ScoredSignal[], minEdgePp: number): LegMetrics {
+  const edgeSignals = signals.filter((s) => s.edge_pp !== 0 && Math.abs(s.edge_pp) >= minEdgePp);
+  const edgeCount = edgeSignals.length;
+  const hits = edgeSignals.filter((s) =>
+    s.edge_pp > 0 ? s.market_now > s.market_then : s.market_now < s.market_then,
+  );
+  const hitRate = edgeCount > 0 ? hits.length / edgeCount : 0;
+  const hitRateData = edgeSignals.map((s) =>
+    s.edge_pp > 0 ? (s.market_now > s.market_then ? 1 : 0) : (s.market_now < s.market_then ? 1 : 0),
+  );
+  const legEventGroups = groupIndicesByEvent(edgeSignals);
+  const hitRateCI: [number, number] = edgeCount > 0
+    ? clusterBootstrapCI(legEventGroups, (sample) => {
+        let sum = 0;
+        for (const idx of sample) sum += hitRateData[idx];
+        return sample.length > 0 ? sum / sample.length : 0;
+      })
+    : [0, 0];
+  const pnl = edgeSignals.reduce((sum, s) => sum + s.pnl, 0);
+  const totalCapital = edgeSignals.reduce((sum, s) => sum + s.capital, 0);
+  const roi = totalCapital > 0 ? pnl / totalCapital : 0;
+  return {
+    edge_signals: edgeCount,
+    edge_hit_rate: hitRate,
+    hit_rate_ci: hitRateCI,
+    flat_bet_pnl: pnl,
+    flat_bet_roi: roi,
+    total_capital: totalCapital,
+  };
+}
+
+const EMPTY_LEG: LegMetrics = {
+  edge_signals: 0,
+  edge_hit_rate: 0,
+  hit_rate_ci: [0, 0],
+  flat_bet_pnl: 0,
+  flat_bet_roi: 0,
+  total_capital: 0,
+};
+
+const EMPTY_BASELINES: BacktestResult['baselines'] = {
+  always_no_roi: 0,
+  always_no_hit_rate: 0,
+  always_yes_roi: 0,
+  always_yes_hit_rate: 0,
+  within_band_skill_pp: 0,
+  within_band_breakdown: [],
+};
+
 /**
  * Compute all backtest metrics from a unified list of scored signals.
  */
-export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<BacktestResult, 'subscription_notice'> {
+export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<BacktestResult, 'subscription_notice' | 'signals_dropped_no_volume' | 'universe_source' | 'universe_size' | 'universe_description' | 'fee_model' | 'flat_bet_pnl_net' | 'flat_bet_roi_net'> {
   const n = signals.length;
   if (n === 0) {
     return {
@@ -75,6 +289,9 @@ export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<B
       flat_bet_roi: 0,
       total_capital: 0,
       signals: [],
+      baselines: EMPTY_BASELINES,
+      resolved_metrics: EMPTY_LEG,
+      unresolved_metrics: EMPTY_LEG,
     };
   }
 
@@ -84,10 +301,14 @@ export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<B
   const brierOctagon = brierOctagonScores.reduce((a, b) => a + b, 0) / n;
   const brierMarket = brierMarketScores.reduce((a, b) => a + b, 0) / n;
 
-  // Skill score with bootstrap CI — resample both
+  // Skill score with EVENT-CLUSTERED bootstrap CI. Why clustered: multi-
+  // outcome events (Fed-cut ladders, election option sets, price strikes)
+  // settle as a block — N contracts from one event aren't N independent
+  // observations. Row-level bootstrap shrinks the CI with sqrt(N rows)
+  // when the right denominator is sqrt(N events).
   const skillScore = computeSkillScore(brierOctagon, brierMarket);
-  const indices = signals.map((_, i) => i);
-  const skillCI = bootstrapCI(indices, (sample) => {
+  const eventGroups = groupIndicesByEvent(signals);
+  const skillCI = clusterBootstrapCI(eventGroups, (sample) => {
     let sumOctagon = 0;
     let sumMarket = 0;
     for (const idx of sample) {
@@ -112,13 +333,16 @@ export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<B
   });
   const hitRate = edgeCount > 0 ? hits.length / edgeCount : 0;
 
-  // Bootstrap hit rate CI
+  // Event-clustered hit rate CI on the EDGE signals only.
   const hitRateData = edgeSignals.map(s => {
     if (s.edge_pp > 0) return s.market_now > s.market_then ? 1 : 0;
     return s.market_now < s.market_then ? 1 : 0;
   });
-  const hitRateCI = bootstrapCI(hitRateData, (sample) => {
-    return sample.reduce((a, b) => a + b, 0) / sample.length;
+  const edgeEventGroups = groupIndicesByEvent(edgeSignals);
+  const hitRateCI = clusterBootstrapCI(edgeEventGroups, (sample) => {
+    let sum = 0;
+    for (const idx of sample) sum += hitRateData[idx];
+    return sample.length > 0 ? sum / sample.length : 0;
   });
 
   // P&L and capital-weighted ROI (matches Supabase methodology):
@@ -161,5 +385,8 @@ export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<B
     flat_bet_roi: roi,
     total_capital: totalCapital,
     signals,
+    baselines: computeBaselines(signals),
+    resolved_metrics: computeLegMetrics(signals.filter((s) => s.resolved), minEdgePp),
+    unresolved_metrics: computeLegMetrics(signals.filter((s) => !s.resolved), minEdgePp),
   };
 }

package/src/backtest/renderer.ts

@@ -5,6 +5,16 @@ export interface FormatOpts {
   minEdge?: number;          // 0-1 scale, default 0.005 (0.5pp)
 }
 
+/** Format a 0-1 ROI as a signed percentage string. */
+function fmtRoi(roi: number): string {
+  return `${roi >= 0 ? '+' : ''}${(roi * 100).toFixed(1)}%`;
+}
+
+/** Format a percentage-point delta with sign. */
+function fmtPp(pp: number): string {
+  return `${pp >= 0 ? '+' : ''}${pp.toFixed(1)}pp`;
+}
+
 /**
  * Format complete backtest result for terminal display.
  */
@@ -17,6 +27,20 @@ export function formatBacktestHuman(result: BacktestResult, opts?: FormatOpts):
 
   const lines: string[] = [];
   lines.push(`Octagon Backtest — ${result.days}-day lookback (${fromStr} – ${toStr})`);
+  lines.push(`Universe: ${result.universe_description}`);
+  let feeHeader: string;
+  switch (result.fee_model) {
+    case 'none':
+      feeHeader = 'none — output is GROSS (pre-fee)';
+      break;
+    case 'taker':
+      feeHeader = 'taker (entries charged Kalshi taker fee = 0.07·p·(1−p))';
+      break;
+    case 'maker':
+      feeHeader = 'maker (free-entry execution assumption — net P&L equals gross)';
+      break;
+  }
+  lines.push(`Fee model: ${feeHeader}`);
   lines.push('══════════════════════════════════════════════════════════');
   lines.push('');
 
@@ -47,9 +71,73 @@ export function formatBacktestHuman(result: BacktestResult, opts?: FormatOpts):
   // lines.push('');
   lines.push(`  Edge signals      ${result.edge_signals}   (min edge: ${minEdgePp}pp)`);
   if (result.edge_signals > 0) {
-    lines.push(`  Hit rate          ${(result.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(result.hit_rate_ci[0] * 100).toFixed(1)}% to ${(result.hit_rate_ci[1] * 100).toFixed(1)}%]`);
-    lines.push(`  Flat-bet P&L      ${result.flat_bet_pnl >= 0 ? '+' : ''}$${result.flat_bet_pnl.toFixed(2)} (ROI: ${result.flat_bet_roi >= 0 ? '+' : ''}${(result.flat_bet_roi * 100).toFixed(1)}%)`);
-    lines.push(`  Capital deployed  $${result.total_capital.toFixed(2)}   (capital-weighted ROI)`);
+    // Resolved settles at 0/100 — realized. Unresolved is marked to the
+    // current Kalshi price — paper P&L that can reverse. Splitting them
+    // makes it visible when one leg is carrying a weak other.
+    const r = result.resolved_metrics;
+    const u = result.unresolved_metrics;
+    if (r.edge_signals > 0) {
+      lines.push('');
+      lines.push('  RESOLVED (realized P&L)');
+      lines.push(`    Hit rate        ${(r.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(r.hit_rate_ci[0] * 100).toFixed(1)}% to ${(r.hit_rate_ci[1] * 100).toFixed(1)}%, event-clustered]   n=${r.edge_signals}`);
+      lines.push(`    Flat-bet P&L    ${fmtRoi(r.flat_bet_roi)} ROI  (${r.flat_bet_pnl >= 0 ? '+' : ''}$${r.flat_bet_pnl.toFixed(2)} on $${r.total_capital.toFixed(2)} capital)`);
+    }
+    if (u.edge_signals > 0) {
+      lines.push('');
+      lines.push('  UNRESOLVED (mark-to-market — paper P&L)');
+      lines.push(`    Directional drift ${(u.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(u.hit_rate_ci[0] * 100).toFixed(1)}% to ${(u.hit_rate_ci[1] * 100).toFixed(1)}%, event-clustered]   n=${u.edge_signals}`);
+      lines.push(`    M2M P&L         ${fmtRoi(u.flat_bet_roi)} ROI  (${u.flat_bet_pnl >= 0 ? '+' : ''}$${u.flat_bet_pnl.toFixed(2)} on $${u.total_capital.toFixed(2)} capital)`);
+    }
+    if (r.edge_signals > 0 && u.edge_signals > 0) {
+      lines.push('');
+      lines.push('  COMBINED (both legs blended — interpret with care)');
+      lines.push(`    Hit rate        ${(result.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(result.hit_rate_ci[0] * 100).toFixed(1)}% to ${(result.hit_rate_ci[1] * 100).toFixed(1)}%, event-clustered]`);
+      lines.push(`    Flat-bet P&L    ${fmtRoi(result.flat_bet_roi)} ROI  (${result.flat_bet_pnl >= 0 ? '+' : ''}$${result.flat_bet_pnl.toFixed(2)} on $${result.total_capital.toFixed(2)} capital)`);
+    }
+    // Fee drag — show only when --fees is on so existing output is unchanged.
+    if (result.fee_model !== 'none' && result.flat_bet_pnl !== result.flat_bet_pnl_net) {
+      const feeDrag = result.flat_bet_pnl - result.flat_bet_pnl_net;
+      lines.push('');
+      lines.push(`  Fees applied (${result.fee_model})`);
+      lines.push(`    Gross P&L       ${result.flat_bet_pnl >= 0 ? '+' : ''}$${result.flat_bet_pnl.toFixed(2)} (${fmtRoi(result.flat_bet_roi)} ROI)`);
+      lines.push(`    Fee drag        -$${feeDrag.toFixed(2)}`);
+      lines.push(`    Net P&L         ${result.flat_bet_pnl_net >= 0 ? '+' : ''}$${result.flat_bet_pnl_net.toFixed(2)} (${fmtRoi(result.flat_bet_roi_net)} ROI)`);
+    } else if (r.edge_signals === 0 && u.edge_signals === 0) {
+      // No edge signals on either leg — fall back to the old single-line view.
+      lines.push(`  Hit rate          ${(result.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(result.hit_rate_ci[0] * 100).toFixed(1)}% to ${(result.hit_rate_ci[1] * 100).toFixed(1)}%]`);
+      lines.push(`  Flat-bet P&L      ${result.flat_bet_pnl >= 0 ? '+' : ''}$${result.flat_bet_pnl.toFixed(2)} (ROI: ${fmtRoi(result.flat_bet_roi)})`);
+    }
+  }
+
+  // ─── Zero-skill baselines ─────────────────────────────────────────────
+  // The headline ROI / hit rate can look strong purely from the universe's
+  // structural NO tilt (multi-outcome events resolve mostly NO). These two
+  // baselines run the same post-filter universe under zero-skill strategies
+  // so the user can see whether the model adds anything.
+  const b = result.baselines;
+  if (result.signals.length > 0) {
+    lines.push('');
+    lines.push('  Zero-skill baselines (same universe, no model):');
+    lines.push(`    Always-NO ROI     ${fmtRoi(b.always_no_roi)}   hit rate ${(b.always_no_hit_rate * 100).toFixed(1)}%`);
+    lines.push(`    Always-YES ROI    ${fmtRoi(b.always_yes_roi)}   hit rate ${(b.always_yes_hit_rate * 100).toFixed(1)}%`);
+    lines.push(`    Within-band skill ${fmtPp(b.within_band_skill_pp)}   (model NO-ROI minus always-NO ROI, capital-weighted across entry-price bands)`);
+    // Per-band breakdown when at least one band has model bets
+    if (b.within_band_breakdown.some((r) => r.n_model > 0)) {
+      lines.push('');
+      lines.push('    Per-band skill breakdown:');
+      lines.push(`      ${'Band'.padEnd(8)}  ${'Model NO ROI'.padStart(13)}  ${'Always-NO ROI'.padStart(14)}  ${'Delta'.padStart(9)}  ${'n_model'.padStart(7)}  ${'n_total'.padStart(7)}`);
+      for (const row of b.within_band_breakdown) {
+        if (row.n_universe === 0) continue;
+        const delta = `${row.skill_delta_pp >= 0 ? '+' : ''}${row.skill_delta_pp.toFixed(1)}pp`;
+        lines.push(`      ${row.band.padEnd(8)}  ${fmtRoi(row.model_no_roi).padStart(13)}  ${fmtRoi(row.always_no_roi).padStart(14)}  ${delta.padStart(9)}  ${String(row.n_model).padStart(7)}  ${String(row.n_universe).padStart(7)}`);
+      }
+    }
+  }
+
+  // Coverage cost of the strict (no lifetime-volume look-ahead) volume gate.
+  if (result.signals_dropped_no_volume > 0) {
+    lines.push('');
+    lines.push(`  Signals dropped: ${result.signals_dropped_no_volume} (no per-contract volume in Octagon snapshot; lifetime-volume fallback removed to avoid look-ahead bias)`);
   }
 
   // Resolved detail table