kalshi-trading-bot-cli 2.1.0

package/src/commands/portfolio.ts

@@ -0,0 +1,236 @@
+import type { ParsedArgs } from './parse-args.js';
+import { formatBoxHeader } from './formatters.js';
+import type { CLIResponse } from './json.js';
+import { wrapSuccess } from './json.js';
+import { getDb } from '../db/index.js';
+import { getOpenPositions, getPositionWithEdge } from '../db/positions.js';
+import type { PositionWithEdge } from '../db/positions.js';
+import { fetchLiveBankroll } from '../risk/kelly.js';
+import { getLatestSnapshot } from '../db/risk.js';
+import type { RiskSnapshot } from '../db/risk.js';
+import { formatTable } from './scan-formatters.js';
+import { computePerformance } from '../eval/performance.js';
+import type { PerformanceStats } from '../eval/performance.js';
+
+export type { PerformanceStats };
+
+export interface PositionView {
+  ticker: string;
+  direction: string;
+  size: number;
+  entryPrice: number;
+  entryEdge: number | null;
+  currentEdge: number | null;
+  unrealizedPnl: number | null;
+  watchdogStatus: string;
+}
+
+export interface PortfolioData {
+  positions: PositionView[];
+  accountSummary: {
+    cashBalance: number;
+    portfolioValue: number;
+    openExposure: number;
+    available: number;
+    positionsCount: number;
+  } | null;
+  riskSnapshot: RiskSnapshot | null;
+  performance?: PerformanceStats;
+}
+
+function deriveWatchdogStatus(pos: PositionWithEdge): string {
+  if (!pos.latest_edge) return 'unknown';
+  const entryEdge = pos.entry_edge ?? 0;
+  const currentEdge = pos.latest_edge.edge;
+
+  // Edge converging toward zero or flipped
+  if (Math.sign(entryEdge) !== Math.sign(currentEdge) && entryEdge !== 0) return 'adverse_move';
+  if (Math.abs(currentEdge) < Math.abs(entryEdge) * 0.5) return 'converging';
+  return 'stable';
+}
+
+export async function handlePortfolio(args: ParsedArgs): Promise<CLIResponse<PortfolioData>> {
+  const db = getDb();
+  const warnings: string[] = [];
+
+  // Get open positions with edge data
+  let positionViews: PositionView[] = [];
+  let positionsCount = 0;
+  try {
+    const openPositions = getOpenPositions(db);
+    const views = openPositions.map((pos) => {
+      const withEdge = getPositionWithEdge(db, pos.position_id);
+      return {
+        ticker: pos.ticker,
+        direction: pos.direction,
+        size: pos.size,
+        entryPrice: pos.entry_price,
+        entryEdge: pos.entry_edge ?? null,
+        currentEdge: withEdge?.latest_edge?.edge ?? null,
+        unrealizedPnl: pos.current_pnl ?? null,
+        watchdogStatus: withEdge ? deriveWatchdogStatus(withEdge) : 'unknown',
+      };
+    });
+    positionViews = views;
+    positionsCount = openPositions.length;
+  } catch (err) {
+    positionsCount = 0;
+    warnings.push(`Positions unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Live bankroll — degrade gracefully on API failure (e.g. 503)
+  let bankroll: Awaited<ReturnType<typeof fetchLiveBankroll>> | null = null;
+  try {
+    bankroll = await fetchLiveBankroll();
+  } catch (err) {
+    warnings.push(`Balance unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Risk snapshot
+  let riskSnapshot: RiskSnapshot | null = null;
+  try {
+    riskSnapshot = getLatestSnapshot(db);
+  } catch (err) {
+    warnings.push(`Risk snapshot unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const data: PortfolioData = {
+    positions: positionViews,
+    accountSummary: bankroll
+      ? {
+          cashBalance: bankroll.cashBalance,
+          portfolioValue: bankroll.portfolioValue,
+          openExposure: bankroll.openExposure,
+          available: bankroll.availableBankroll,
+          positionsCount,
+        }
+      : null,
+    riskSnapshot,
+  };
+
+  // Performance stats if requested
+  if (args.performance) {
+    try {
+      data.performance = computePerformance(db);
+    } catch (err) {
+      warnings.push(`Performance unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  const meta: CLIResponse<PortfolioData>['meta'] = {
+    ...(bankroll
+      ? {
+          bankroll: {
+            cash_balance: bankroll.cashBalance,
+            portfolio_value: bankroll.portfolioValue,
+            open_exposure: bankroll.openExposure,
+            available: bankroll.availableBankroll,
+            positions_count: positionsCount,
+          },
+        }
+      : {}),
+    ...(warnings.length > 0 ? { warnings } : {}),
+  };
+
+  return wrapSuccess('portfolio', data, meta);
+}
+
+export function formatPortfolioHuman(data: PortfolioData): string {
+  const lines: string[] = [];
+
+  lines.push(...formatBoxHeader('PORTFOLIO'));
+  lines.push('');
+
+  // Positions table
+  if (data.positions.length === 0) {
+    lines.push('  No open positions.');
+  } else {
+    const rows = data.positions.map((p) => [
+      p.ticker,
+      p.direction.toUpperCase(),
+      String(p.size),
+      `$${(p.entryPrice / 100).toFixed(2)}`,
+      p.currentEdge !== null ? `${(p.currentEdge * 100).toFixed(1)}%` : '-',
+      p.unrealizedPnl !== null ? `$${(p.unrealizedPnl / 100).toFixed(2)}` : '-',
+      p.watchdogStatus,
+    ]);
+    lines.push(formatTable(
+      ['Ticker', 'Dir', 'Size', 'Entry', 'Current Edge', 'P&L', 'Status'],
+      rows
+    ));
+  }
+  lines.push('');
+
+  // Account summary
+  lines.push('  Account Summary:');
+  if (data.accountSummary) {
+    lines.push(`    Cash Balance:    $${(data.accountSummary.cashBalance / 100).toFixed(2)}`);
+    lines.push(`    Portfolio Value: $${(data.accountSummary.portfolioValue / 100).toFixed(2)}`);
+    lines.push(`    Open Exposure:   $${(data.accountSummary.openExposure / 100).toFixed(2)}`);
+    lines.push(`    Available:       $${(data.accountSummary.available / 100).toFixed(2)}`);
+    lines.push(`    Positions:       ${data.accountSummary.positionsCount}`);
+  } else {
+    lines.push('    (unavailable — Kalshi API returned an error)');
+  }
+  lines.push('');
+
+  // Risk snapshot
+  if (data.riskSnapshot) {
+    const snap = data.riskSnapshot;
+    lines.push('  Risk Snapshot:');
+    if (snap.drawdown_current != null) {
+      lines.push(`    Current Drawdown: ${(snap.drawdown_current * 100).toFixed(1)}%`);
+    }
+    if (snap.drawdown_max != null) {
+      lines.push(`    Max Drawdown:     ${(snap.drawdown_max * 100).toFixed(1)}%`);
+    }
+    if (snap.daily_pnl != null) {
+      lines.push(`    Daily P&L:        $${(snap.daily_pnl / 100).toFixed(2)}`);
+    }
+    if (snap.circuit_breaker_on) {
+      lines.push('    Circuit Breaker:  ACTIVE');
+    }
+    lines.push('');
+  }
+
+  // Performance stats
+  if (data.performance) {
+    const perf = data.performance;
+    lines.push('  Performance:');
+    if (perf.winRate !== null) {
+      lines.push(`    Win Rate:    ${(perf.winRate * 100).toFixed(1)}%`);
+    }
+    lines.push(`    Total P&L:   $${(perf.totalPnl / 100).toFixed(2)}`);
+    if (perf.sharpeRatio !== null) {
+      lines.push(`    Sharpe Ratio: ${perf.sharpeRatio.toFixed(2)}`);
+    }
+
+    const brierEntries = Object.entries(perf.brierByCategory);
+    if (brierEntries.length > 0) {
+      lines.push('');
+      lines.push('  Brier Scores by Category:');
+      const brierRows = brierEntries.map(([cat, score]) => [cat, score.toFixed(3)]);
+      lines.push(formatTable(['Category', 'Brier Score'], brierRows));
+    }
+
+    const pnlEntries = Object.entries(perf.pnlByCategory);
+    if (pnlEntries.length > 0) {
+      lines.push('');
+      lines.push('  P&L by Category:');
+      const pnlRows = pnlEntries.map(([cat, pnl]) => [cat, `$${(pnl / 100).toFixed(2)}`]);
+      lines.push(formatTable(['Category', 'P&L'], pnlRows));
+    }
+
+    if (perf.underperformingCategories && perf.underperformingCategories.length > 0) {
+      lines.push('');
+      lines.push('  ⚠ Underperforming Categories (Brier > 0.30):');
+      for (const cat of perf.underperformingCategories) {
+        const score = perf.brierByCategory[cat];
+        lines.push(`    - ${cat}: ${score !== undefined ? score.toFixed(3) : 'N/A'}`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/commands/review.ts

@@ -0,0 +1,176 @@
+import { callKalshiApi } from '../tools/kalshi/api.js';
+import type { KalshiPosition } from '../tools/kalshi/types.js';
+import { handleAnalyze } from './analyze.js';
+import type { AnalyzeData } from './analyze.js';
+import { parsePriceField } from '../controllers/browse.js';
+import { formatBoxHeader } from './formatters.js';
+
+export interface PositionReview {
+  ticker: string;
+  direction: 'yes' | 'no';
+  size: number;
+  entryPrice: number | null;
+  currentMarketProb: number;
+  modelProb: number;
+  edge: number;
+  signal: 'HOLD' | 'SELL';
+  sellSide: 'yes' | 'no';
+  closePriceCents: number;
+  reason: string;
+  analyzeError?: string;
+}
+
+const SELL_THRESHOLD = 0.03; // minimum edge reversal to trigger SELL signal
+
+/**
+ * Fetch all live Kalshi positions with non-zero holdings,
+ * run edge analysis on each, and return HOLD/SELL recommendations.
+ */
+export async function reviewPortfolio(): Promise<PositionReview[]> {
+  const data = await callKalshiApi('GET', '/portfolio/positions');
+  const allPositions = (data.market_positions ?? data.positions ?? []) as KalshiPosition[];
+
+  const nonZero = allPositions.filter((p) => {
+    const pos = parseFloat(String(p.position ?? '0'));
+    return pos !== 0;
+  });
+
+  if (nonZero.length === 0) return [];
+
+  // Run analysis concurrently (cached — no Octagon credits consumed)
+  // Pass preloaded position to avoid N+1 portfolio fetches inside handleAnalyze
+  const results = await Promise.allSettled(
+    nonZero.map((p) => {
+      const rawPos = parseFloat(String(p.position ?? '0'));
+      const pos = rawPos !== 0
+        ? { direction: (rawPos > 0 ? 'yes' : 'no') as 'yes' | 'no', size: Math.abs(Math.round(rawPos)) }
+        : null;
+      return handleAnalyze(p.ticker, false, pos);
+    })
+  );
+
+  return results.map((result, i) => {
+    const pos = nonZero[i];
+    const rawPos = parseFloat(String(pos.position ?? '0'));
+    const direction: 'yes' | 'no' = rawPos > 0 ? 'yes' : 'no';
+    const size = Math.abs(Math.round(rawPos));
+
+    if (result.status === 'rejected') {
+      const err = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      return {
+        ticker: pos.ticker,
+        direction,
+        size,
+        entryPrice: null,
+        currentMarketProb: 0,
+        modelProb: 0,
+        edge: 0,
+        signal: 'HOLD' as const,
+        sellSide: direction,
+        closePriceCents: 0,
+        reason: 'Analysis failed — manual review required',
+        analyzeError: err,
+      };
+    }
+
+    const analysis: AnalyzeData = result.value;
+    const { edge, marketProb, modelProb, kelly } = analysis;
+
+    // Determine if edge has reversed against our position
+    let signal: 'HOLD' | 'SELL' = 'HOLD';
+    let reason = '';
+
+    if (direction === 'yes' && edge < -SELL_THRESHOLD) {
+      signal = 'SELL';
+      reason = `Edge reversed: model now favors NO by ${Math.abs(edge * 100).toFixed(0)}pp`;
+    } else if (direction === 'no' && edge > SELL_THRESHOLD) {
+      signal = 'SELL';
+      reason = `Edge reversed: model now favors YES by ${(edge * 100).toFixed(0)}pp`;
+    } else if (direction === 'yes' && edge >= 0) {
+      reason = `Still favorable: +${(edge * 100).toFixed(0)}pp edge`;
+    } else if (direction === 'no' && edge <= 0) {
+      reason = `Still favorable: ${(edge * 100).toFixed(0)}pp edge`;
+    } else {
+      // Edge has decayed but not reversed past threshold
+      const decay = direction === 'yes' ? edge : -edge;
+      reason = `Edge decayed (${(decay * 100).toFixed(0)}pp) but below sell threshold`;
+    }
+
+    // Use the bid-derived close price from handleAnalyze when available,
+    // fall back to marketProb approximation only if missing
+    const closePriceCents =
+      analysis.closePriceCents && analysis.closePriceCents > 0
+        ? analysis.closePriceCents
+        : Math.round(
+            direction === 'yes'
+              ? marketProb * 100 - 1
+              : (1 - marketProb) * 100 - 1
+          );
+
+    return {
+      ticker: pos.ticker,
+      direction,
+      size,
+      entryPrice: kelly.entryPriceCents > 0 ? kelly.entryPriceCents : null,
+      currentMarketProb: marketProb,
+      modelProb,
+      edge,
+      signal,
+      sellSide: direction,
+      closePriceCents: Math.max(1, closePriceCents),
+      reason,
+    };
+  });
+}
+
+export function formatReviewHuman(reviews: PositionReview[]): string {
+  const lines: string[] = [];
+
+  lines.push(...formatBoxHeader('PORTFOLIO REVIEW'));
+  lines.push('');
+
+  if (reviews.length === 0) {
+    lines.push('  No open positions found.');
+    return lines.join('\n');
+  }
+
+  const sells = reviews.filter((r) => r.signal === 'SELL');
+  const holds = reviews.filter((r) => r.signal === 'HOLD');
+
+  lines.push(`  ${reviews.length} position${reviews.length === 1 ? '' : 's'} analyzed  |  ${sells.length} SELL signal${sells.length === 1 ? '' : 's'}  |  ${holds.length} HOLD`);
+  lines.push('');
+
+  // Show SELL signals first
+  for (const r of sells) {
+    const dirLabel = r.direction.toUpperCase();
+    const edgePp = `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`;
+    lines.push(`  ⚠  ${r.ticker}  ${dirLabel} ×${r.size}`);
+    lines.push(`     Edge: ${edgePp}  |  ${r.reason}`);
+    lines.push(`     → SELL ${dirLabel} @ ${r.closePriceCents}¢`);
+    lines.push(`     Command: /sell ${r.ticker} ${r.size} ${r.closePriceCents} ${r.direction}`);
+    if (r.analyzeError) {
+      lines.push(`     ⚠ Analysis error: ${r.analyzeError}`);
+    }
+    lines.push('');
+  }
+
+  // Show HOLD positions
+  for (const r of holds) {
+    const dirLabel = r.direction.toUpperCase();
+    const edgePp = `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`;
+    lines.push(`  ✓  ${r.ticker}  ${dirLabel} ×${r.size}`);
+    lines.push(`     Edge: ${edgePp}  |  ${r.reason}`);
+    if (r.analyzeError) {
+      lines.push(`     ⚠ Analysis error: ${r.analyzeError}`);
+    }
+    lines.push('');
+  }
+
+  if (sells.length > 0) {
+    lines.push(`  Run the commands above to close flagged positions, or use /analyze <ticker> for details.`);
+  } else {
+    lines.push('  All positions are within acceptable edge range. No closes recommended.');
+  }
+
+  return lines.join('\n');
+}

package/src/commands/scan-formatters.ts

@@ -0,0 +1,98 @@
+import type { ScanResult } from '../scan/loop.js';
+import type { EdgeSnapshot } from '../scan/types.js';
+import type { EdgeRow } from '../db/edge.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+export function formatTable(headers: string[], rows: string[][]): string {
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const pad = (s: string, w: number) => s.padEnd(w);
+  const sep = '─';
+
+  const topBorder = '┌' + colWidths.map((w) => sep.repeat(w + 2)).join('┬') + '┐';
+  const headerRow = '│' + headers.map((h, i) => ` ${pad(h, colWidths[i])} `).join('│') + '│';
+  const midBorder = '├' + colWidths.map((w) => sep.repeat(w + 2)).join('┼') + '┤';
+  const bottomBorder = '└' + colWidths.map((w) => sep.repeat(w + 2)).join('┴') + '┘';
+
+  const dataRows = rows.map(
+    (row) => '│' + colWidths.map((w, i) => ` ${pad(row[i] ?? '', w)} `).join('│') + '│'
+  );
+
+  return [topBorder, headerRow, midBorder, ...dataRows, bottomBorder].join('\n');
+}
+
+function fmtEdge(edge: number): string {
+  const pct = (edge * 100).toFixed(1);
+  return edge >= 0 ? `+${pct}%` : `${pct}%`;
+}
+
+function fmtProb(prob: number): string {
+  return `${(prob * 100).toFixed(1)}%`;
+}
+
+function fmtTimestamp(epoch: number): string {
+  const d = new Date(epoch * 1000);
+  const now = Date.now();
+  const diffMs = now - d.getTime();
+  const diffMin = Math.floor(diffMs / 60_000);
+
+  if (diffMin < 1) return 'just now';
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}
+
+export function formatScanTable(result: ScanResult): string {
+  const lines: string[] = [];
+
+  if (result.edgeSnapshots.length === 0) {
+    lines.push('No edges found in this scan.');
+  } else {
+    const rows = result.edgeSnapshots.map((s) => [
+      s.ticker,
+      fmtProb(s.modelProb),
+      fmtProb(s.marketProb),
+      fmtEdge(s.edge),
+      s.confidence,
+      truncate(s.drivers[0]?.claim ?? '-', 40),
+    ]);
+
+    lines.push(formatTable(
+      ['Ticker', 'Model%', 'Market%', 'Edge', 'Confidence', 'Top Driver'],
+      rows
+    ));
+  }
+
+  const actionable = result.edgeSnapshots.filter(
+    (s) => s.confidence === 'high' || s.confidence === 'very_high'
+  ).length;
+  const secs = (result.duration / 1000).toFixed(1);
+  lines.push('');
+  lines.push(`Scanned ${result.eventsScanned} events, found ${actionable} actionable edges in ${secs}s`);
+
+  return lines.join('\n');
+}
+
+export function formatEdgeTable(rows: EdgeRow[]): string {
+  if (rows.length === 0) return 'No edges found.';
+
+  const tableRows = rows.map((r) => [
+    r.ticker,
+    fmtProb(r.model_prob),
+    fmtProb(r.market_prob),
+    fmtEdge(r.edge),
+    r.confidence ?? '-',
+    fmtTimestamp(r.timestamp),
+  ]);
+
+  return formatTable(
+    ['Ticker', 'Model%', 'Market%', 'Edge', 'Confidence', 'Timestamp'],
+    tableRows
+  );
+}

package/src/commands/scan.ts

@@ -0,0 +1,38 @@
+import type { ParsedArgs } from './parse-args.js';
+import type { CLIResponse } from './json.js';
+import type { ScanResult } from '../scan/loop.js';
+import { wrapSuccess, wrapError } from './json.js';
+import { getDb } from '../db/index.js';
+import { auditTrail } from '../audit/index.js';
+import { ScanLoop } from '../scan/loop.js';
+import { createOctagonInvoker } from '../scan/invoker.js';
+import { formatScanTable } from './scan-formatters.js';
+
+export async function handleScan(args: ParsedArgs): Promise<CLIResponse<ScanResult>> {
+  const db = getDb();
+  const invoker = createOctagonInvoker();
+  const loop = new ScanLoop(db, auditTrail, invoker);
+
+  const result = await loop.runOnce({
+    theme: args.theme ?? 'top50',
+    dryRun: args.dryRun,
+  });
+
+  const actionable = result.edgeSnapshots.filter(
+    (s) => s.confidence === 'high' || s.confidence === 'very_high'
+  ).length;
+
+  const meta: CLIResponse<ScanResult>['meta'] = {
+    scan_id: result.scanId,
+    theme: args.theme ?? 'top50',
+    events_scanned: result.eventsScanned,
+    actionable,
+    octagon_credits_used: result.octagonCreditsUsed,
+  };
+
+  return wrapSuccess('scan', result, meta);
+}
+
+export function formatScanHuman(result: ScanResult): string {
+  return formatScanTable(result);
+}

package/src/commands/search-edge.ts

@@ -0,0 +1,139 @@
+import type { Database } from 'bun:sqlite';
+
+export interface EdgeMarket {
+  market_ticker: string;
+  event_ticker: string;
+  model_prob: number;       // 0-100
+  market_prob: number;      // 0-100
+  edge_pp: number;          // model - market
+  direction: 'YES' | 'NO';
+  series_category: string;
+  confidence_score: number;
+}
+
+export interface EdgeScanResult {
+  markets: EdgeMarket[];
+  total_scanned: number;
+  events_scanned: number;
+}
+
+/**
+ * Scan all cached Octagon events for markets with edge above a threshold.
+ * Reads directly from SQLite — zero API calls, instant response.
+ */
+export function scanEdges(
+  db: Database,
+  opts?: { minEdgePp?: number; limit?: number; category?: string },
+): EdgeScanResult {
+  const minEdgePp = opts?.minEdgePp ?? 5;
+  const limit = opts?.limit ?? 20;
+  const category = opts?.category;
+
+  const nowIso = new Date().toISOString();
+  let inner = `SELECT event_ticker, MAX(fetched_at) as max_fetched
+    FROM octagon_reports WHERE variant_used = 'events-api' AND outcome_probabilities_json IS NOT NULL
+    AND (close_time IS NULL OR close_time > $now)`;
+  const params: Record<string, string> = { $now: nowIso };
+  if (category) {
+    inner += ' AND LOWER(series_category) LIKE $cat';
+    params.$cat = `%${category.toLowerCase()}%`;
+  }
+  inner += ' GROUP BY event_ticker';
+
+  const query = `SELECT r.event_ticker, r.series_category, r.confidence_score, r.outcome_probabilities_json
+    FROM octagon_reports r
+    INNER JOIN (${inner}) latest ON r.event_ticker = latest.event_ticker AND r.fetched_at = latest.max_fetched
+    WHERE r.variant_used = 'events-api' AND r.outcome_probabilities_json IS NOT NULL`;
+
+  const rows = db.query(query).all(params) as Array<{
+    event_ticker: string;
+    series_category: string | null;
+    confidence_score: number | null;
+    outcome_probabilities_json: string;
+  }>;
+
+  const allMarkets: EdgeMarket[] = [];
+  let totalScanned = 0;
+
+  for (const row of rows) {
+    let outcomes: Array<{ market_ticker: string; model_probability: number; market_probability: number }>;
+    try {
+      outcomes = JSON.parse(row.outcome_probabilities_json);
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(outcomes)) continue;
+
+    for (const o of outcomes) {
+      if (typeof o.model_probability !== 'number' || typeof o.market_probability !== 'number') continue;
+      if (!o.market_ticker) continue;
+      // Skip illiquid markets with no trading activity
+      if (o.market_probability <= 0) continue;
+      totalScanned++;
+      const edgePp = Math.round((o.model_probability - o.market_probability) * 10) / 10;
+      if (Math.abs(edgePp) < minEdgePp) continue;
+
+      allMarkets.push({
+        market_ticker: o.market_ticker,
+        event_ticker: row.event_ticker,
+        model_prob: o.model_probability,
+        market_prob: o.market_probability,
+        edge_pp: edgePp,
+        direction: edgePp > 0 ? 'YES' : 'NO',
+        series_category: row.series_category ?? '',
+        confidence_score: row.confidence_score ?? 0,
+      });
+    }
+  }
+
+  // Sort by |edge| descending
+  allMarkets.sort((a, b) => Math.abs(b.edge_pp) - Math.abs(a.edge_pp));
+
+  return {
+    markets: allMarkets.slice(0, limit),
+    total_scanned: totalScanned,
+    events_scanned: rows.length,
+  };
+}
+
+export function formatEdgeScanHuman(result: EdgeScanResult, minEdgePp: number): string {
+  const lines: string[] = [];
+  lines.push(`Octagon Edge Scanner — ${result.events_scanned} events, ${result.total_scanned} markets scanned`);
+  lines.push('════════════════════════════════════════════════════════');
+  lines.push('');
+
+  if (result.markets.length === 0) {
+    lines.push(`  No markets with |edge| ≥ ${minEdgePp}pp found.`);
+    return lines.join('\n');
+  }
+
+  const header = '  ' + [
+    '#'.padStart(3),
+    'Ticker'.padEnd(35),
+    'Model'.padStart(6),
+    'Market'.padStart(7),
+    'Edge'.padStart(7),
+    'Dir'.padStart(5),
+    'Category'.padEnd(15),
+  ].join('  ');
+  lines.push(header);
+
+  for (let i = 0; i < result.markets.length; i++) {
+    const m = result.markets[i];
+    const row = '  ' + [
+      String(i + 1).padStart(3),
+      m.market_ticker.padEnd(35),
+      `${m.model_prob.toFixed(0)}%`.padStart(6),
+      `${m.market_prob.toFixed(0)}%`.padStart(7),
+      `${m.edge_pp >= 0 ? '+' : ''}${m.edge_pp.toFixed(0)}pp`.padStart(7),
+      m.direction.padStart(5),
+      m.series_category.padEnd(15),
+    ].join('  ');
+    lines.push(row);
+  }
+
+  lines.push('');
+  lines.push(`${result.markets.length} markets with |edge| ≥ ${minEdgePp}pp`);
+
+  return lines.join('\n');
+}