Trading Risk Guardian

// NEVER exceed these — hard coded, not configurable
const HARD_LIMITS = {
  WHEEL:     0.35,   // 35% of account value
  STRANGLE:  0.45,   // 45% of account value
  ZEDTE:     0.15,   // 15% of account value
  FALLBACK:  0.10,   // 10% of account value
  DAILY_LOSS: 0.05,  // -5% in one day → halt for the day
  MAX_DRAWDOWN: 0.10, // -10% from peak → full halt
} as const;

Position Sizing Formulas

Wheel (CSP/CC)

// 1 contract per $2,300 of buying power (1 contract = 100 shares)
// Never exceed 35% total Wheel allocation
function wheelContractSize(account: Account, strikePrice: number): number {
  const maxAlloc     = account.value * HARD_LIMITS.WHEEL;
  const currentWheelAlloc = getWheelAllocation(account);
  const available    = maxAlloc - currentWheelAlloc;
  const bpPerContract = strikePrice * 100;  // 1 contract = 100 shares × strike
  const maxContracts = Math.floor(available / bpPerContract);
  return Math.max(0, Math.min(maxContracts, 1));  // Start with 1 contract per symbol
}

Strangle

// Risk: 2% of account per strangle (3x premium stop defines max loss)
// Position size: (account * 0.02) / (3 × premium_received)
function strangleContracts(account: Account, premiumReceived: number): number {
  const riskAmount   = account.value * 0.02;  // 2% risk
  const stopLoss     = premiumReceived * 3;   // 3x = max loss
  const contracts    = Math.floor(riskAmount / (stopLoss * 100));
  return Math.max(1, Math.min(contracts, 5));
}

0DTE

// 0.5% of account — keep small, trade frequently
function zeroDteContracts(account: Account, premiumReceived: number): number {
  const maxRisk  = account.value * 0.005;    // 0.5% max risk
  const maxLoss  = premiumReceived * 100;    // 1x premium = max loss for butterfly
  return Math.max(1, Math.floor(maxRisk / maxLoss));
}

Portfolio Risk Check — Master Gate

interface RiskCheckResult {
  canTrade:    boolean;
  reason?:     string;
  reduceSize?: boolean;  // Suggests half-size if cautious but tradeable
}

export class PortfolioRisk {
  async check(account: Account): Promise<RiskCheckResult> {
    // Layer 4: Kill switch (fastest check first)
    if (await isKillSwitchActive()) {
      return { canTrade: false, reason: 'KILL_SWITCH_ACTIVE' };
    }

    // Layer 2: VIX gate
    const vix = await getVIX();
    if (vix > config.MAX_VIX_TO_TRADE) {
      await sendAlert({ level: 'WARNING', subject: `VIX ${vix} — entries suspended`, throttleKey: 'vix-spike' });
      return { canTrade: false, reason: `VIX_TOO_HIGH:${vix}` };
    }

    // Layer 5: Daily P&L gate
    const todayPnL    = await posRepo.getTodayRealizedPnL();
    const dailyLossPct = todayPnL / account.value;
    if (dailyLossPct < -HARD_LIMITS.DAILY_LOSS) {
      await sendAlert({
        level:        'CRITICAL',
        subject:      `Daily loss limit hit: ${(dailyLossPct * 100).toFixed(2)}%`,
        body:         `Today P&L: $${todayPnL.toFixed(0)}. All new entries halted for today.`,
        throttleKey:  'daily-loss',
      });
      return { canTrade: false, reason: 'DAILY_LOSS_LIMIT' };
    }

    // Layer 6: Portfolio drawdown gate
    const drawdown = await posRepo.getMaxDrawdown();
    if (drawdown > HARD_LIMITS.MAX_DRAWDOWN) {
      await sendAlert({
        level:       'CRITICAL',
        subject:     `MAX DRAWDOWN EXCEEDED: ${(drawdown * 100).toFixed(2)}%`,
        body:        'Full trading halt. Manual restart required via kill switch.',
        throttleKey: 'drawdown',
      });
      return { canTrade: false, reason: 'MAX_DRAWDOWN_EXCEEDED' };
    }

    // Layer 7: Per-track allocation gates
    const allocs = await this.getAllocations(account);
    if (allocs.WHEEL    >= HARD_LIMITS.WHEEL)    return { canTrade: false, reason: 'WHEEL_OVER_ALLOCATED' };
    if (allocs.STRANGLE >= HARD_LIMITS.STRANGLE) return { canTrade: false, reason: 'STRANGLE_OVER_ALLOCATED' };
    if (allocs.ZEDTE    >= HARD_LIMITS.ZEDTE)    return { canTrade: false, reason: 'ZEDTE_OVER_ALLOCATED' };

    // Layer 8: Portfolio delta gate (warning but tradeable)
    const portfolioDelta = await this.getPortfolioDelta();
    if (Math.abs(portfolioDelta) > 0.50) {
      await sendAlert({ level: 'WARNING', subject: `Portfolio delta skewed: ${portfolioDelta.toFixed(2)}`, throttleKey: 'delta-skew' });
      return { canTrade: true, reduceSize: true, reason: 'DELTA_ELEVATED' };
    }

    return { canTrade: true };
  }

  private async getAllocations(account: Account): Promise<Record<string, number>> {
    const positions = await posRepo.getAllOpen();
    const calcAlloc = (track: string) => {
      const trackPositions = positions.filter(p => p.track === track);
      const totalBP = trackPositions.reduce((sum, p) => sum + p.buyingPowerUsed, 0);
      return totalBP / account.value;
    };
    return {
      WHEEL:    calcAlloc('WHEEL'),
      STRANGLE: calcAlloc('STRANGLE'),
      ZEDTE:    calcAlloc('0DTE'),
      FALLBACK: calcAlloc('IRON_CONDOR'),
    };
  }

  private async getPortfolioDelta(): Promise<number> {
    const positions = await posRepo.getAllOpen();
    return positions.reduce((sum, p) => sum + (p.currentDelta * p.contracts * 100), 0);
  }
}

Kill Switch — File-Based Manual Override

// File: .bot_stopped (in working directory)
// To halt: touch .bot_stopped
// To resume: rm .bot_stopped
// Also accessible via API: POST /api/bot/stop | POST /api/bot/start

const KILL_SWITCH_PATH = path.join(process.cwd(), '.bot_stopped');

async function isKillSwitchActive(): Promise<boolean> {
  try {
    await fs.access(KILL_SWITCH_PATH);
    return true;   // File exists → bot stopped
  } catch {
    return false;  // File absent → bot running
  }
}

async function activateKillSwitch(reason: string): Promise<void> {
  await fs.writeFile(KILL_SWITCH_PATH, `Stopped at ${new Date().toISOString()}: ${reason}`);
  await sendAlert({ level: 'CRITICAL', subject: `Kill switch activated: ${reason}` });
  logger.error('Kill switch activated', { reason });
}

Safety Events — Full Matrix

Implementation Checklist

• portfolioRisk.check() called FIRST in every runMainCycle() before any routing
• HARD_LIMITS defined as as const — not in config, not from env
• Kill switch checks file system, not in-memory flag (survives process restart)
• Daily loss gate resets at market open each day (not UTC midnight)
• Drawdown calculated from all-time equity peak, not just recent positions
• All safety alerts have throttleKey to prevent email spam on repeated triggers
• Track allocation uses buying power tied up, not nominal position value
• Portfolio delta sum includes ALL tracks, not per-track
• Safety events logged to audit_log with full context
• API endpoints /api/bot/stop and /api/bot/start write/delete kill switch file