docs: add persistent agent constraints document (issue #100)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -16,8 +16,9 @@ CONFIDENCE_THRESHOLD=80
 # Database
 DB_PATH=data/trade_logs.db
 
-# Rate Limiting
+# Rate Limiting (requests per second for KIS API)
-RATE_LIMIT_RPS=10.0
+# Reduced to 5.0 to avoid "초당 거래건수 초과" errors (EGW00201)
+RATE_LIMIT_RPS=5.0
 
 # Trading Mode (paper / live)
 MODE=paper

CLAUDE.md

@@ -45,6 +45,39 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra
 
 **Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.
 
+## Smart Volatility Scanner (Optional)
+
+Python-first filtering pipeline that reduces Gemini API calls by pre-filtering stocks using technical indicators.
+
+### How It Works
+
+1. **Fetch Rankings** — KIS API volume surge rankings (top 30 stocks)
+2. **Python Filter** — RSI + volume ratio calculations (no AI)
+   - Volume > 200% of previous day
+   - RSI(14) < 30 (oversold) OR RSI(14) > 70 (momentum)
+3. **AI Judgment** — Only qualified candidates (1-3 stocks) sent to Gemini
+
+### Configuration
+
+Add to `.env` (optional, has sensible defaults):
+```bash
+RSI_OVERSOLD_THRESHOLD=30    # 0-50, default 30
+RSI_MOMENTUM_THRESHOLD=70    # 50-100, default 70
+VOL_MULTIPLIER=2.0           # Volume threshold (2.0 = 200%)
+SCANNER_TOP_N=3              # Max candidates per scan
+```
+
+### Benefits
+
+- **Reduces API costs** — Process 1-3 stocks instead of 20-30
+- **Python-based filtering** — Fast technical analysis before AI
+- **Evolution-ready** — Selection context logged for strategy optimization
+- **Fault-tolerant** — Falls back to static watchlist on API failure
+
+### Realtime Mode Only
+
+Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchlists for batch efficiency.
+
 ## Documentation
 
 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
@@ -53,6 +86,7 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra
 - **[Context Tree](docs/context-tree.md)** — L1-L7 hierarchical memory system
 - **[Testing](docs/testing.md)** — Test structure, coverage requirements, writing tests
 - **[Agent Policies](docs/agents.md)** — Prime directives, constraints, prohibited actions
+- **[Requirements Log](docs/requirements-log.md)** — User requirements and feedback tracking
 
 ## Core Principles
 
@@ -61,10 +95,20 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra
 3. **Issue-Driven Development** — All work goes through Gitea issues → feature branches → PRs
 4. **Agent Specialization** — Use dedicated agents for design, coding, testing, docs, review
 
+## Requirements Management
+
+User requirements and feedback are tracked in [docs/requirements-log.md](docs/requirements-log.md):
+
+- New requirements are added chronologically with dates
+- Code changes should reference related requirements
+- Helps maintain project evolution aligned with user needs
+- Preserves context across conversations and development cycles
+
 ## Project Structure
 
 ```
 src/
+├── analysis/        # Technical analysis (RSI, volatility, smart scanner)
 ├── broker/          # KIS API client (domestic + overseas)
 ├── brain/           # Gemini AI decision engine
 ├── core/            # Risk manager (READ-ONLY)
@@ -75,7 +119,7 @@ src/
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)
 
-tests/               # 273 tests across 13 files
+tests/               # 343 tests across 14 files
 docs/                # Extended documentation
 ```
 

docs/agent-constraints.md

@@ -0,0 +1,45 @@
+# Agent Constraints
+
+This document records **persistent behavioral constraints** for agents working on this repository.
+It is distinct from `docs/requirements-log.md`, which records **project/product requirements**.
+
+## Scope
+
+- Applies to all AI agents and automation that modify this repo.
+- Supplements (does not replace) `docs/agents.md` and `docs/workflow.md`.
+
+## Persistent Rules
+
+1. **Workflow enforcement**
+   - Follow `docs/workflow.md` for all changes.
+   - Create a Gitea issue before any code or documentation change.
+   - Work on a feature branch `feature/issue-{N}-{short-description}` and open a PR.
+   - Never commit directly to `main`.
+
+2. **Document-first routing**
+   - When performing work, consult relevant `docs/` files *before* making changes.
+   - Route decisions to the documented policy whenever applicable.
+   - If guidance conflicts, prefer the stricter/safety-first rule and note it in the PR.
+
+3. **Docs with code**
+   - Any code change must be accompanied by relevant documentation updates.
+   - If no doc update is needed, state the reason explicitly in the PR.
+
+4. **Session-persistent user constraints**
+   - If the user requests that a behavior should persist across sessions, record it here
+     (or in a dedicated policy doc) and reference it when working.
+   - Keep entries short and concrete, with dates.
+
+## Change Control
+
+- Changes to this file follow the same workflow as code changes.
+- Keep the history chronological and minimize rewording of existing entries.
+
+## History
+
+### 2026-02-08
+
+- Always enforce Gitea workflow: issue -> feature branch -> PR before changes.
+- When work requires guidance, consult the relevant `docs/` policies first.
+- Any code change must be accompanied by relevant documentation updates.
+- Persist user constraints across sessions by recording them in this document.

docs/architecture.md

@@ -2,7 +2,42 @@
 
 ## Overview
 
-Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates four components in a 60-second cycle per stock across multiple markets.
+Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates four components across multiple markets with two trading modes: daily (batch API calls) or realtime (per-stock decisions).
+
+## Trading Modes
+
+The system supports two trading frequency modes controlled by the `TRADE_MODE` environment variable:
+
+### Daily Mode (default)
+
+Optimized for Gemini Free tier API limits (20 calls/day):
+
+- **Batch decisions**: 1 API call per market per session
+- **Fixed schedule**: 4 sessions per day at 6-hour intervals (configurable)
+- **API efficiency**: Processes all stocks in a market simultaneously
+- **Use case**: Free tier users, cost-conscious deployments
+- **Configuration**:
+  ```bash
+  TRADE_MODE=daily
+  DAILY_SESSIONS=4        # Sessions per day (1-10)
+  SESSION_INTERVAL_HOURS=6  # Hours between sessions (1-24)
+  ```
+
+**Example**: With 2 markets (US, KR) and 4 sessions/day = 8 API calls/day (within 20 call limit)
+
+### Realtime Mode
+
+High-frequency trading with individual stock analysis:
+
+- **Per-stock decisions**: 1 API call per stock per cycle
+- **60-second interval**: Continuous monitoring
+- **Use case**: Production deployments with Gemini paid tier
+- **Configuration**:
+  ```bash
+  TRADE_MODE=realtime
+  ```
+
+**Note**: Realtime mode requires Gemini API subscription due to high call volume.
 
 ## Core Components
 
@@ -29,7 +64,39 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - `get_open_markets()` returns currently active markets
 - `get_next_market_open()` finds next market to open and when
 
-### 2. Brain (`src/brain/gemini_client.py`)
+**New API Methods** (added in v0.9.0):
+- `fetch_market_rankings()` — Fetch volume surge rankings from KIS API
+- `get_daily_prices()` — Fetch OHLCV history for technical analysis
+
+### 2. Analysis (`src/analysis/`)
+
+**VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations
+
+- ATR (Average True Range) for volatility measurement
+- RSI (Relative Strength Index) using Wilder's smoothing method
+- Price change percentages across multiple timeframes
+- Volume surge ratios and price-volume divergence
+- Momentum scoring (0-100 scale)
+- Breakout/breakdown pattern detection
+
+**SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline
+
+- **Step 1**: Fetch volume rankings from KIS API (top 30 stocks)
+- **Step 2**: Calculate RSI and volume ratio for each stock
+- **Step 3**: Apply filters:
+  - Volume ratio >= `VOL_MULTIPLIER` (default 2.0x previous day)
+  - RSI < `RSI_OVERSOLD_THRESHOLD` (30) OR RSI > `RSI_MOMENTUM_THRESHOLD` (70)
+- **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%)
+- **Step 5**: Return top N candidates (default 3) for AI analysis
+- **Fallback**: Uses static watchlist if ranking API unavailable
+- **Realtime mode only**: Daily mode uses batch processing for API efficiency
+
+**Benefits:**
+- Reduces Gemini API calls from 20-30 stocks to 1-3 qualified candidates
+- Fast Python-based filtering before expensive AI judgment
+- Logs selection context (RSI, volume_ratio, signal, score) for Evolution system
+
+### 3. Brain (`src/brain/gemini_client.py`)
 
 **GeminiClient** — AI decision engine powered by Google Gemini
 
@@ -39,7 +106,7 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - Falls back to safe HOLD on any parse/API error
 - Handles markdown-wrapped JSON, malformed responses, invalid actions
 
-### 3. Risk Manager (`src/core/risk_manager.py`)
+### 4. Risk Manager (`src/core/risk_manager.py`)
 
 **RiskManager** — Safety circuit breaker and order validation
 
@@ -51,7 +118,7 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
   - Must always be enforced, cannot be disabled
 
-### 4. Notifications (`src/notifications/telegram_client.py`)
+### 5. Notifications (`src/notifications/telegram_client.py`)
 
 **TelegramClient** — Real-time event notifications via Telegram Bot API
 
@@ -70,7 +137,7 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 
 **Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
 
-### 5. Evolution (`src/evolution/optimizer.py`)
+### 6. Evolution (`src/evolution/optimizer.py`)
 
 **StrategyOptimizer** — Self-improvement loop
 
@@ -82,9 +149,11 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 
 ## Data Flow
 
+### Realtime Mode (with Smart Scanner)
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ Main Loop (60s cycle per stock, per market)                │
+│ Main Loop (60s cycle per market)                           │
 └─────────────────────────────────────────────────────────────┘
                            │
                            ▼
@@ -97,6 +166,21 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
                            │
                            ▼
         ┌──────────────────────────────────┐
+        │ Smart Scanner (Python-first)      │
+        │ - Fetch volume rankings (KIS)    │
+        │ - Get 20d price history per stock│
+        │ - Calculate RSI(14) + vol ratio  │
+        │ - Filter: vol>2x AND RSI extreme │
+        │ - Return top 3 qualified stocks  │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ For Each Qualified Candidate      │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
         │ Broker: Fetch Market Data        │
         │ - Domestic: orderbook + balance  │
         │ - Overseas: price + balance      │
@@ -110,7 +194,7 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
                            │
                            ▼
         ┌──────────────────────────────────┐
-        │ Brain: Get Decision               │
+        │ Brain: Get Decision (AI)          │
         │ - Build prompt with market data   │
         │ - Call Gemini API                 │
         │ - Parse JSON response             │
@@ -146,6 +230,9 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
         │ - SQLite (data/trades.db)         │
         │ - Track: action, confidence,      │
         │   rationale, market, exchange     │
+        │ - NEW: selection_context (JSON)   │
+        │   - RSI, volume_ratio, signal     │
+        │   - For Evolution optimization    │
         └───────────────────────────────────┘
 ```
 
@@ -165,11 +252,24 @@ CREATE TABLE trades (
     price REAL,
     pnl REAL DEFAULT 0.0,
     market TEXT DEFAULT 'KR',       -- KR | US_NASDAQ | JP | etc.
-    exchange_code TEXT DEFAULT 'KRX' -- KRX | NASD | NYSE | etc.
+    exchange_code TEXT DEFAULT 'KRX', -- KRX | NASD | NYSE | etc.
+    selection_context TEXT          -- JSON: {rsi, volume_ratio, signal, score}
 );
 ```
 
-Auto-migration: Adds `market` and `exchange_code` columns if missing for backward compatibility.
+**Selection Context** (new in v0.9.0): Stores scanner selection criteria as JSON:
+```json
+{
+  "rsi": 28.5,
+  "volume_ratio": 2.7,
+  "signal": "oversold",
+  "score": 85.2
+}
+```
+
+Enables Evolution system to analyze correlation between selection criteria and trade outcomes.
+
+Auto-migration: Adds `market`, `exchange_code`, and `selection_context` columns if missing for backward compatibility.
 
 ## Configuration
 
@@ -192,10 +292,21 @@ MAX_LOSS_PCT=3.0
 MAX_ORDER_PCT=30.0
 ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
 
+# Trading Mode (API efficiency)
+TRADE_MODE=daily              # daily | realtime
+DAILY_SESSIONS=4              # Sessions per day (daily mode only)
+SESSION_INTERVAL_HOURS=6      # Hours between sessions (daily mode only)
+
 # Telegram Notifications (optional)
 TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 TELEGRAM_CHAT_ID=123456789
 TELEGRAM_ENABLED=true
+
+# Smart Scanner (optional, realtime mode only)
+RSI_OVERSOLD_THRESHOLD=30    # 0-50, oversold threshold
+RSI_MOMENTUM_THRESHOLD=70    # 50-100, momentum threshold
+VOL_MULTIPLIER=2.0           # Minimum volume ratio (2.0 = 200%)
+SCANNER_TOP_N=3              # Max qualified candidates per scan
 ```
 
 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.

docs/requirements-log.md

@@ -0,0 +1,66 @@
+# Requirements Log
+
+프로젝트 진화를 위한 사용자 요구사항 기록.
+
+이 문서는 시간순으로 사용자와의 대화에서 나온 요구사항과 피드백을 기록합니다.
+새로운 요구사항이 있으면 날짜와 함께 추가하세요.
+
+---
+
+## 2026-02-05
+
+### API 효율화
+- Gemini API는 귀중한 자원. 종목별 개별 호출 대신 배치 호출 필요
+- Free tier 한도(20 calls/day) 고려하여 일일 몇 차례 거래 모드로 전환
+- 배치 API 호출로 여러 종목을 한 번에 분석
+
+### 거래 모드
+- **Daily Mode**: 하루 4회 거래 세션 (6시간 간격) - Free tier 호환
+- **Realtime Mode**: 60초 간격 실시간 거래 - 유료 구독 필요
+- `TRADE_MODE` 환경변수로 모드 선택
+
+### 진화 시스템
+- 사용자 대화 내용을 문서로 기록하여 향후에도 의도 반영
+- 프롬프트 품질 검증은 별도 이슈로 다룰 예정
+
+### 문서화
+- 시스템 구조, 기능별 설명 등 코드 문서화 항상 신경쓸 것
+- 새로운 기능 추가 시 관련 문서 업데이트 필수
+
+---
+
+## 2026-02-06
+
+### Smart Volatility Scanner (Python-First, AI-Last 파이프라인)
+
+**배경:**
+- 정적 종목 리스트를 순회하는 방식은 비효율적
+- KIS API 거래량 순위를 통해 시장 주도주를 자동 탐지해야 함
+- Gemini API 호출 전에 Python 기반 기술적 분석으로 필터링 필요
+
+**요구사항:**
+1. KIS API 거래량 순위 API 통합 (`fetch_market_rankings`)
+2. 일별 가격 히스토리 API 추가 (`get_daily_prices`)
+3. RSI(14) 계산 기능 구현 (Wilder's smoothing method)
+4. 필터 조건:
+   - 거래량 > 전일 대비 200% (VOL_MULTIPLIER)
+   - RSI < 30 (과매도) OR RSI > 70 (모멘텀)
+5. 상위 1-3개 적격 종목만 Gemini에 전달
+6. 종목 선정 배경(RSI, volume_ratio, signal, score) 데이터베이스 기록
+
+**구현 결과:**
+- `src/analysis/smart_scanner.py`: SmartVolatilityScanner 클래스
+- `src/analysis/volatility.py`: calculate_rsi() 메서드 추가
+- `src/broker/kis_api.py`: 2개 신규 API 메서드
+- `src/db.py`: selection_context 컬럼 추가
+- 설정 가능한 임계값: RSI_OVERSOLD_THRESHOLD, RSI_MOMENTUM_THRESHOLD, VOL_MULTIPLIER, SCANNER_TOP_N
+
+**효과:**
+- Gemini API 호출 20-30개 → 1-3개로 감소
+- Python 기반 빠른 필터링 → 비용 절감
+- 선정 기준 추적 → Evolution 시스템 최적화 가능
+- API 장애 시 정적 watchlist로 자동 전환
+
+**참고:** Realtime 모드 전용. Daily 모드는 배치 효율성을 위해 정적 watchlist 사용.
+
+**이슈/PR:** #76, #77

src/analysis/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from src.analysis.scanner import MarketScanner
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
 from src.analysis.volatility import VolatilityAnalyzer
 
-__all__ = ["VolatilityAnalyzer", "MarketScanner"]
+__all__ = ["VolatilityAnalyzer", "MarketScanner", "SmartVolatilityScanner", "ScanCandidate"]

src/analysis/scanner.py

@@ -42,6 +42,7 @@ class MarketScanner:
         volatility_analyzer: VolatilityAnalyzer,
         context_store: ContextStore,
         top_n: int = 5,
+        max_concurrent_scans: int = 1,
     ) -> None:
         """Initialize the market scanner.
 
@@ -51,12 +52,14 @@ class MarketScanner:
             volatility_analyzer: Volatility analyzer instance
             context_store: Context store for L7 real-time data
             top_n: Number of top movers to return per market (default 5)
+            max_concurrent_scans: Max concurrent stock scans (default 1, fully serialized)
         """
         self.broker = broker
         self.overseas_broker = overseas_broker
         self.analyzer = volatility_analyzer
         self.context_store = context_store
         self.top_n = top_n
+        self._scan_semaphore = asyncio.Semaphore(max_concurrent_scans)
 
     async def scan_stock(
         self,
@@ -83,8 +86,8 @@ class MarketScanner:
                 # Convert to orderbook-like structure
                 orderbook = {
                     "output1": {
-                        "stck_prpr": price_data.get("output", {}).get("last", "0"),
+                        "stck_prpr": price_data.get("output", {}).get("last", "0") or "0",
-                        "acml_vol": price_data.get("output", {}).get("tvol", "0"),
+                        "acml_vol": price_data.get("output", {}).get("tvol", "0") or "0",
                     }
                 }
 
@@ -139,8 +142,12 @@ class MarketScanner:
 
         logger.info("Scanning %s market (%d stocks)", market.name, len(stock_codes))
 
-        # Scan all stocks concurrently (with rate limiting handled by broker)
+        # Scan stocks with bounded concurrency to prevent API rate limit burst
-        tasks = [self.scan_stock(code, market) for code in stock_codes]
+        async def _bounded_scan(code: str) -> VolatilityMetrics | None:
+            async with self._scan_semaphore:
+                return await self.scan_stock(code, market)
+
+        tasks = [_bounded_scan(code) for code in stock_codes]
         results = await asyncio.gather(*tasks)
 
         # Filter out failures and sort by momentum score

src/analysis/smart_scanner.py

@@ -0,0 +1,192 @@
+"""Smart Volatility Scanner with RSI and volume filters.
+
+Fetches market rankings from KIS API and applies technical filters
+to identify high-probability trading candidates.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from src.analysis.volatility import VolatilityAnalyzer
+from src.broker.kis_api import KISBroker
+from src.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScanCandidate:
+    """A qualified candidate from the smart scanner."""
+
+    stock_code: str
+    name: str
+    price: float
+    volume: float
+    volume_ratio: float  # Current volume / previous day volume
+    rsi: float
+    signal: str  # "oversold" or "momentum"
+    score: float  # Composite score for ranking
+
+
+class SmartVolatilityScanner:
+    """Scans market rankings and applies RSI/volume filters.
+
+    Flow:
+    1. Fetch volume rankings from KIS API
+    2. For each ranked stock, fetch daily prices
+    3. Calculate RSI and volume ratio
+    4. Apply filters: volume > VOL_MULTIPLIER AND (RSI < 30 OR RSI > 70)
+    5. Return top N qualified candidates
+    """
+
+    def __init__(
+        self,
+        broker: KISBroker,
+        volatility_analyzer: VolatilityAnalyzer,
+        settings: Settings,
+    ) -> None:
+        """Initialize the smart scanner.
+
+        Args:
+            broker: KIS broker for API calls
+            volatility_analyzer: Analyzer for RSI calculation
+            settings: Application settings
+        """
+        self.broker = broker
+        self.analyzer = volatility_analyzer
+        self.settings = settings
+
+        # Extract scanner settings
+        self.rsi_oversold = settings.RSI_OVERSOLD_THRESHOLD
+        self.rsi_momentum = settings.RSI_MOMENTUM_THRESHOLD
+        self.vol_multiplier = settings.VOL_MULTIPLIER
+        self.top_n = settings.SCANNER_TOP_N
+
+    async def scan(
+        self,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Execute smart scan and return qualified candidates.
+
+        Args:
+            fallback_stocks: Stock codes to use if ranking API fails
+
+        Returns:
+            List of ScanCandidate, sorted by score, up to top_n items
+        """
+        # Step 1: Fetch rankings
+        try:
+            rankings = await self.broker.fetch_market_rankings(
+                ranking_type="volume",
+                limit=30,  # Fetch more than needed for filtering
+            )
+            logger.info("Fetched %d stocks from volume rankings", len(rankings))
+        except ConnectionError as exc:
+            logger.warning("Ranking API failed, using fallback: %s", exc)
+            if fallback_stocks:
+                # Create minimal ranking data for fallback
+                rankings = [
+                    {
+                        "stock_code": code,
+                        "name": code,
+                        "price": 0,
+                        "volume": 0,
+                        "change_rate": 0,
+                        "volume_increase_rate": 0,
+                    }
+                    for code in fallback_stocks
+                ]
+            else:
+                return []
+
+        # Step 2: Analyze each stock
+        candidates: list[ScanCandidate] = []
+
+        for stock in rankings:
+            stock_code = stock["stock_code"]
+            if not stock_code:
+                continue
+
+            try:
+                # Fetch daily prices for RSI calculation
+                daily_prices = await self.broker.get_daily_prices(stock_code, days=20)
+
+                if len(daily_prices) < 15:  # Need at least 14+1 for RSI
+                    logger.debug("Insufficient price history for %s", stock_code)
+                    continue
+
+                # Calculate RSI
+                close_prices = [p["close"] for p in daily_prices]
+                rsi = self.analyzer.calculate_rsi(close_prices, period=14)
+
+                # Calculate volume ratio (today vs previous day avg)
+                if len(daily_prices) >= 2:
+                    prev_day_volume = daily_prices[-2]["volume"]
+                    current_volume = stock.get("volume", 0) or daily_prices[-1]["volume"]
+                    volume_ratio = (
+                        current_volume / prev_day_volume if prev_day_volume > 0 else 1.0
+                    )
+                else:
+                    volume_ratio = stock.get("volume_increase_rate", 0) / 100 + 1  # Fallback
+
+                # Apply filters
+                volume_qualified = volume_ratio >= self.vol_multiplier
+                rsi_oversold = rsi < self.rsi_oversold
+                rsi_momentum = rsi > self.rsi_momentum
+
+                if volume_qualified and (rsi_oversold or rsi_momentum):
+                    signal = "oversold" if rsi_oversold else "momentum"
+
+                    # Calculate composite score
+                    # Higher score for: extreme RSI + high volume
+                    rsi_extremity = abs(rsi - 50) / 50  # 0-1 scale
+                    volume_score = min(volume_ratio / 5, 1.0)  # Cap at 5x
+                    score = (rsi_extremity * 0.6 + volume_score * 0.4) * 100
+
+                    candidates.append(
+                        ScanCandidate(
+                            stock_code=stock_code,
+                            name=stock.get("name", stock_code),
+                            price=stock.get("price", daily_prices[-1]["close"]),
+                            volume=current_volume,
+                            volume_ratio=volume_ratio,
+                            rsi=rsi,
+                            signal=signal,
+                            score=score,
+                        )
+                    )
+
+                    logger.info(
+                        "Qualified: %s (%s) RSI=%.1f vol=%.1fx signal=%s score=%.1f",
+                        stock_code,
+                        stock.get("name", ""),
+                        rsi,
+                        volume_ratio,
+                        signal,
+                        score,
+                    )
+
+            except ConnectionError as exc:
+                logger.warning("Failed to analyze %s: %s", stock_code, exc)
+                continue
+            except Exception as exc:
+                logger.error("Unexpected error analyzing %s: %s", stock_code, exc)
+                continue
+
+        # Sort by score and return top N
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        return candidates[: self.top_n]
+
+    def get_stock_codes(self, candidates: list[ScanCandidate]) -> list[str]:
+        """Extract stock codes from candidates for watchlist update.
+
+        Args:
+            candidates: List of scan candidates
+
+        Returns:
+            List of stock codes
+        """
+        return [c.stock_code for c in candidates]

src/analysis/volatility.py

@@ -124,6 +124,54 @@ class VolatilityAnalyzer:
             return 1.0
         return current_volume / avg_volume
 
+    def calculate_rsi(
+        self,
+        close_prices: list[float],
+        period: int = 14,
+    ) -> float:
+        """Calculate Relative Strength Index (RSI) using Wilder's smoothing.
+
+        Args:
+            close_prices: List of closing prices (oldest to newest, minimum period+1 values)
+            period: RSI period (default 14)
+
+        Returns:
+            RSI value between 0 and 100, or 50.0 (neutral) if insufficient data
+
+        Examples:
+            >>> analyzer = VolatilityAnalyzer()
+            >>> prices = [100 - i * 0.5 for i in range(20)]  # Downtrend
+            >>> rsi = analyzer.calculate_rsi(prices)
+            >>> assert rsi < 50  # Oversold territory
+        """
+        if len(close_prices) < period + 1:
+            return 50.0  # Neutral RSI if insufficient data
+
+        # Calculate price changes
+        changes = [close_prices[i] - close_prices[i - 1] for i in range(1, len(close_prices))]
+
+        # Separate gains and losses
+        gains = [max(0.0, change) for change in changes]
+        losses = [max(0.0, -change) for change in changes]
+
+        # Calculate initial average gain/loss (simple average for first period)
+        avg_gain = sum(gains[:period]) / period
+        avg_loss = sum(losses[:period]) / period
+
+        # Apply Wilder's smoothing for remaining periods
+        for i in range(period, len(changes)):
+            avg_gain = (avg_gain * (period - 1) + gains[i]) / period
+            avg_loss = (avg_loss * (period - 1) + losses[i]) / period
+
+        # Calculate RS and RSI
+        if avg_loss == 0:
+            return 100.0  # All gains, maximum RSI
+
+        rs = avg_gain / avg_loss
+        rsi = 100 - (100 / (1 + rs))
+
+        return rsi
+
     def calculate_pv_divergence(
         self,
         price_change: float,

src/brain/gemini_client.py

@@ -525,3 +525,233 @@ class GeminiClient:
             DecisionCache instance or None if caching disabled
         """
         return self._cache
+
+    # ------------------------------------------------------------------
+    # Batch Decision Making (for daily trading mode)
+    # ------------------------------------------------------------------
+
+    async def decide_batch(
+        self, stocks_data: list[dict[str, Any]]
+    ) -> dict[str, TradeDecision]:
+        """Make decisions for multiple stocks in a single API call.
+
+        This is designed for daily trading mode to minimize API usage
+        when working with Gemini Free tier (20 calls/day limit).
+
+        Args:
+            stocks_data: List of market data dictionaries, each with:
+                - stock_code: Stock ticker
+                - current_price: Current price
+                - market_name: Market name (optional)
+                - foreigner_net: Foreigner net buy/sell (optional)
+
+        Returns:
+            Dictionary mapping stock_code to TradeDecision
+
+        Example:
+            >>> stocks_data = [
+            ...     {"stock_code": "AAPL", "current_price": 185.5},
+            ...     {"stock_code": "MSFT", "current_price": 420.0},
+            ... ]
+            >>> decisions = await client.decide_batch(stocks_data)
+            >>> decisions["AAPL"].action
+            'BUY'
+        """
+        if not stocks_data:
+            return {}
+
+        # Build compressed batch prompt
+        market_name = stocks_data[0].get("market_name", "stock market")
+
+        # Format stock data as compact JSON array
+        compact_stocks = []
+        for stock in stocks_data:
+            compact = {
+                "code": stock["stock_code"],
+                "price": stock["current_price"],
+            }
+            if stock.get("foreigner_net", 0) != 0:
+                compact["frgn"] = stock["foreigner_net"]
+            compact_stocks.append(compact)
+
+        data_str = json.dumps(compact_stocks, ensure_ascii=False)
+
+        prompt = (
+            f"You are a professional {market_name} trading analyst.\n"
+            "Analyze the following stocks and decide whether to BUY, SELL, or HOLD each one.\n\n"
+            f"Stock Data: {data_str}\n\n"
+            "You MUST respond with ONLY a valid JSON array in this format:\n"
+            '[{"code": "AAPL", "action": "BUY", "confidence": 85, "rationale": "..."},\n'
+            ' {"code": "MSFT", "action": "HOLD", "confidence": 50, "rationale": "..."}, ...]\n\n'
+            "Rules:\n"
+            "- Return one decision object per stock\n"
+            "- action must be exactly: BUY, SELL, or HOLD\n"
+            "- confidence must be 0-100\n"
+            "- rationale should be concise (1-2 sentences)\n"
+            "- Do NOT wrap JSON in markdown code blocks\n"
+        )
+
+        # Estimate tokens
+        token_count = self._optimizer.estimate_tokens(prompt)
+        self._total_tokens_used += token_count
+
+        logger.info(
+            "Requesting batch decision for %d stocks from Gemini",
+            len(stocks_data),
+            extra={"estimated_tokens": token_count},
+        )
+
+        try:
+            response = await self._client.aio.models.generate_content(
+                model=self._model_name,
+                contents=prompt,
+            )
+            raw = response.text
+        except Exception as exc:
+            logger.error("Gemini API error in batch decision: %s", exc)
+            # Return HOLD for all stocks on API error
+            return {
+                stock["stock_code"]: TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale=f"API error: {exc}",
+                    token_count=token_count,
+                    cached=False,
+                )
+                for stock in stocks_data
+            }
+
+        # Parse batch response
+        return self._parse_batch_response(raw, stocks_data, token_count)
+
+    def _parse_batch_response(
+        self, raw: str, stocks_data: list[dict[str, Any]], token_count: int
+    ) -> dict[str, TradeDecision]:
+        """Parse batch response into a dictionary of decisions.
+
+        Args:
+            raw: Raw response from Gemini
+            stocks_data: Original stock data list
+            token_count: Token count for the request
+
+        Returns:
+            Dictionary mapping stock_code to TradeDecision
+        """
+        if not raw or not raw.strip():
+            logger.warning("Empty batch response from Gemini — defaulting all to HOLD")
+            return {
+                stock["stock_code"]: TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale="Empty response",
+                    token_count=0,
+                    cached=False,
+                )
+                for stock in stocks_data
+            }
+
+        # Strip markdown code fences if present
+        cleaned = raw.strip()
+        match = re.search(r"```(?:json)?\s*\n?(.*?)\n?```", cleaned, re.DOTALL)
+        if match:
+            cleaned = match.group(1).strip()
+
+        try:
+            data = json.loads(cleaned)
+        except json.JSONDecodeError:
+            logger.warning("Malformed JSON in batch response — defaulting all to HOLD")
+            return {
+                stock["stock_code"]: TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale="Malformed JSON response",
+                    token_count=0,
+                    cached=False,
+                )
+                for stock in stocks_data
+            }
+
+        if not isinstance(data, list):
+            logger.warning("Batch response is not a JSON array — defaulting all to HOLD")
+            return {
+                stock["stock_code"]: TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale="Invalid response format",
+                    token_count=0,
+                    cached=False,
+                )
+                for stock in stocks_data
+            }
+
+        # Build decision map
+        decisions: dict[str, TradeDecision] = {}
+        stock_codes = {stock["stock_code"] for stock in stocks_data}
+
+        for item in data:
+            if not isinstance(item, dict):
+                continue
+
+            code = item.get("code")
+            if not code or code not in stock_codes:
+                continue
+
+            # Validate required fields
+            if not all(k in item for k in ("action", "confidence", "rationale")):
+                logger.warning("Missing fields for %s — using HOLD", code)
+                decisions[code] = TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale="Missing required fields",
+                    token_count=0,
+                    cached=False,
+                )
+                continue
+
+            action = str(item["action"]).upper()
+            if action not in VALID_ACTIONS:
+                logger.warning("Invalid action '%s' for %s — forcing HOLD", action, code)
+                action = "HOLD"
+
+            confidence = int(item["confidence"])
+            rationale = str(item["rationale"])
+
+            # Enforce confidence threshold
+            if confidence < self._confidence_threshold:
+                logger.info(
+                    "Confidence %d < threshold %d for %s — forcing HOLD",
+                    confidence,
+                    self._confidence_threshold,
+                    code,
+                )
+                action = "HOLD"
+
+            decisions[code] = TradeDecision(
+                action=action,
+                confidence=confidence,
+                rationale=rationale,
+                token_count=token_count // len(stocks_data),  # Split token cost
+                cached=False,
+            )
+            self._total_decisions += 1
+
+        # Fill in missing stocks with HOLD
+        for stock in stocks_data:
+            code = stock["stock_code"]
+            if code not in decisions:
+                logger.warning("No decision for %s in batch response — using HOLD", code)
+                decisions[code] = TradeDecision(
+                    action="HOLD",
+                    confidence=0,
+                    rationale="Not found in batch response",
+                    token_count=0,
+                    cached=False,
+                )
+
+        logger.info(
+            "Batch decision completed for %d stocks",
+            len(decisions),
+            extra={"tokens": token_count},
+        )
+
+        return decisions

src/broker/kis_api.py

@@ -56,6 +56,8 @@ class KISBroker:
         self._access_token: str | None = None
         self._token_expires_at: float = 0.0
         self._token_lock = asyncio.Lock()
+        self._last_refresh_attempt: float = 0.0
+        self._refresh_cooldown: float = 60.0  # Seconds (matches KIS 1/minute limit)
         self._rate_limiter = LeakyBucket(settings.RATE_LIMIT_RPS)
 
     def _get_session(self) -> aiohttp.ClientSession:
@@ -98,7 +100,19 @@ class KISBroker:
             if self._access_token and now < self._token_expires_at:
                 return self._access_token
 
+            # Check cooldown period (prevents hitting EGW00133: 1/minute limit)
+            time_since_last_attempt = now - self._last_refresh_attempt
+            if time_since_last_attempt < self._refresh_cooldown:
+                remaining = self._refresh_cooldown - time_since_last_attempt
+                error_msg = (
+                    f"Token refresh on cooldown. "
+                    f"Retry in {remaining:.1f}s (KIS allows 1/minute)"
+                )
+                logger.warning(error_msg)
+                raise ConnectionError(error_msg)
+
             logger.info("Refreshing KIS access token")
+            self._last_refresh_attempt = now
             session = self._get_session()
             url = f"{self._base_url}/oauth2/tokenP"
             body = {
@@ -124,6 +138,7 @@ class KISBroker:
 
     async def _get_hash_key(self, body: dict[str, Any]) -> str:
         """Request a hash key from KIS for POST request body signing."""
+        await self._rate_limiter.acquire()
         session = self._get_session()
         url = f"{self._base_url}/uapi/hashkey"
         headers = {
@@ -265,3 +280,153 @@ class KISBroker:
                 return data
         except (TimeoutError, aiohttp.ClientError) as exc:
             raise ConnectionError(f"Network error sending order: {exc}") from exc
+
+    async def fetch_market_rankings(
+        self,
+        ranking_type: str = "volume",
+        limit: int = 30,
+    ) -> list[dict[str, Any]]:
+        """Fetch market rankings from KIS API.
+
+        Args:
+            ranking_type: Type of ranking ("volume" or "fluctuation")
+            limit: Maximum number of results to return
+
+        Returns:
+            List of stock data dicts with keys: stock_code, name, price, volume,
+            change_rate, volume_increase_rate
+
+        Raises:
+            ConnectionError: If API request fails
+        """
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        # TR_ID for volume ranking
+        tr_id = "FHPST01710000" if ranking_type == "volume" else "FHPST01710100"
+        headers = await self._auth_headers(tr_id)
+
+        params = {
+            "FID_COND_MRKT_DIV_CODE": "J",  # Stock/ETF/ETN
+            "FID_COND_SCR_DIV_CODE": "20001",  # Volume surge
+            "FID_INPUT_ISCD": "0000",  # All stocks
+            "FID_DIV_CLS_CODE": "0",  # All types
+            "FID_BLNG_CLS_CODE": "0",
+            "FID_TRGT_CLS_CODE": "111111111",
+            "FID_TRGT_EXLS_CLS_CODE": "000000",
+            "FID_INPUT_PRICE_1": "0",
+            "FID_INPUT_PRICE_2": "0",
+            "FID_VOL_CNT": "0",
+            "FID_INPUT_DATE_1": "",
+        }
+
+        url = f"{self._base_url}/uapi/domestic-stock/v1/quotations/volume-rank"
+
+        try:
+            async with session.get(url, headers=headers, params=params) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    raise ConnectionError(
+                        f"fetch_market_rankings failed ({resp.status}): {text}"
+                    )
+                data = await resp.json()
+
+            # Parse response - output is a list of ranked stocks
+            def _safe_float(value: str | float | None, default: float = 0.0) -> float:
+                if value is None or value == "":
+                    return default
+                try:
+                    return float(value)
+                except (ValueError, TypeError):
+                    return default
+
+            rankings = []
+            for item in data.get("output", [])[:limit]:
+                rankings.append({
+                    "stock_code": item.get("mksc_shrn_iscd", ""),
+                    "name": item.get("hts_kor_isnm", ""),
+                    "price": _safe_float(item.get("stck_prpr", "0")),
+                    "volume": _safe_float(item.get("acml_vol", "0")),
+                    "change_rate": _safe_float(item.get("prdy_ctrt", "0")),
+                    "volume_increase_rate": _safe_float(item.get("vol_inrt", "0")),
+                })
+            return rankings
+
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching rankings: {exc}") from exc
+
+    async def get_daily_prices(
+        self,
+        stock_code: str,
+        days: int = 20,
+    ) -> list[dict[str, Any]]:
+        """Fetch daily OHLCV price history for a stock.
+
+        Args:
+            stock_code: 6-digit stock code
+            days: Number of trading days to fetch (default 20 for RSI calculation)
+
+        Returns:
+            List of daily price dicts with keys: date, open, high, low, close, volume
+            Sorted oldest to newest
+
+        Raises:
+            ConnectionError: If API request fails
+        """
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        headers = await self._auth_headers("FHKST03010100")
+
+        # Calculate date range (today and N days ago)
+        from datetime import datetime, timedelta
+        end_date = datetime.now().strftime("%Y%m%d")
+        start_date = (datetime.now() - timedelta(days=days + 10)).strftime("%Y%m%d")
+
+        params = {
+            "FID_COND_MRKT_DIV_CODE": "J",
+            "FID_INPUT_ISCD": stock_code,
+            "FID_INPUT_DATE_1": start_date,
+            "FID_INPUT_DATE_2": end_date,
+            "FID_PERIOD_DIV_CODE": "D",  # Daily
+            "FID_ORG_ADJ_PRC": "0",  # Adjusted price
+        }
+
+        url = f"{self._base_url}/uapi/domestic-stock/v1/quotations/inquire-daily-itemchartprice"
+
+        try:
+            async with session.get(url, headers=headers, params=params) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    raise ConnectionError(
+                        f"get_daily_prices failed ({resp.status}): {text}"
+                    )
+                data = await resp.json()
+
+            # Parse response
+            def _safe_float(value: str | float | None, default: float = 0.0) -> float:
+                if value is None or value == "":
+                    return default
+                try:
+                    return float(value)
+                except (ValueError, TypeError):
+                    return default
+
+            prices = []
+            for item in data.get("output2", []):
+                prices.append({
+                    "date": item.get("stck_bsop_date", ""),
+                    "open": _safe_float(item.get("stck_oprc", "0")),
+                    "high": _safe_float(item.get("stck_hgpr", "0")),
+                    "low": _safe_float(item.get("stck_lwpr", "0")),
+                    "close": _safe_float(item.get("stck_clpr", "0")),
+                    "volume": _safe_float(item.get("acml_vol", "0")),
+                })
+
+            # Sort oldest to newest (KIS returns newest first)
+            prices.reverse()
+
+            return prices[:days]  # Return only requested number of days
+
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching daily prices: {exc}") from exc

src/config.py

@@ -33,17 +33,37 @@ class Settings(BaseSettings):
     FAT_FINGER_PCT: float = Field(default=30.0, gt=0.0, le=100.0)
     CONFIDENCE_THRESHOLD: int = Field(default=80, ge=0, le=100)
 
+    # Smart Scanner Configuration
+    RSI_OVERSOLD_THRESHOLD: int = Field(default=30, ge=0, le=50)
+    RSI_MOMENTUM_THRESHOLD: int = Field(default=70, ge=50, le=100)
+    VOL_MULTIPLIER: float = Field(default=2.0, gt=1.0, le=10.0)
+    SCANNER_TOP_N: int = Field(default=3, ge=1, le=10)
+
     # Database
     DB_PATH: str = "data/trade_logs.db"
 
     # Rate Limiting (requests per second for KIS API)
-    RATE_LIMIT_RPS: float = 10.0
+    # Conservative limit to avoid EGW00201 "초당 거래건수 초과" errors.
+    # KIS API real limit is ~2 RPS; 2.0 provides maximum safety.
+    RATE_LIMIT_RPS: float = 2.0
 
     # Trading mode
     MODE: str = Field(default="paper", pattern="^(paper|live)$")
 
+    # Trading frequency mode (daily = batch API calls, realtime = per-stock calls)
+    TRADE_MODE: str = Field(default="daily", pattern="^(daily|realtime)$")
+    DAILY_SESSIONS: int = Field(default=4, ge=1, le=10)
+    SESSION_INTERVAL_HOURS: int = Field(default=6, ge=1, le=24)
+
+    # Pre-Market Planner
+    PRE_MARKET_MINUTES: int = Field(default=30, ge=10, le=120)
+    MAX_SCENARIOS_PER_STOCK: int = Field(default=5, ge=1, le=10)
+    PLANNER_TIMEOUT_SECONDS: int = Field(default=60, ge=10, le=300)
+    DEFENSIVE_PLAYBOOK_ON_FAILURE: bool = True
+    RESCAN_INTERVAL_SECONDS: int = Field(default=300, ge=60, le=900)
+
     # Market selection (comma-separated market codes)
-    ENABLED_MARKETS: str = "KR"
+    ENABLED_MARKETS: str = "KR,US"
 
     # Backup and Disaster Recovery (optional)
     BACKUP_ENABLED: bool = True
@@ -59,6 +79,10 @@ class Settings(BaseSettings):
     TELEGRAM_CHAT_ID: str | None = None
     TELEGRAM_ENABLED: bool = True
 
+    # Telegram Commands (optional)
+    TELEGRAM_COMMANDS_ENABLED: bool = True
+    TELEGRAM_POLLING_INTERVAL: float = 1.0  # seconds
+
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
     @property

src/db.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import sqlite3
 from datetime import UTC, datetime
 from pathlib import Path
@@ -38,6 +39,8 @@ def init_db(db_path: str) -> sqlite3.Connection:
         conn.execute("ALTER TABLE trades ADD COLUMN market TEXT DEFAULT 'KR'")
     if "exchange_code" not in columns:
         conn.execute("ALTER TABLE trades ADD COLUMN exchange_code TEXT DEFAULT 'KRX'")
+    if "selection_context" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN selection_context TEXT")
 
     # Context tree tables for multi-layered memory management
     conn.execute(
@@ -118,15 +121,33 @@ def log_trade(
     pnl: float = 0.0,
     market: str = "KR",
     exchange_code: str = "KRX",
+    selection_context: dict[str, any] | None = None,
 ) -> None:
-    """Insert a trade record into the database."""
+    """Insert a trade record into the database.
+
+    Args:
+        conn: Database connection
+        stock_code: Stock code
+        action: Trade action (BUY/SELL/HOLD)
+        confidence: Confidence level (0-100)
+        rationale: AI decision rationale
+        quantity: Number of shares
+        price: Trade price
+        pnl: Profit/loss
+        market: Market code
+        exchange_code: Exchange code
+        selection_context: Scanner selection data (RSI, volume_ratio, signal, score)
+    """
+    # Serialize selection context to JSON
+    context_json = json.dumps(selection_context) if selection_context else None
+
     conn.execute(
         """
         INSERT INTO trades (
             timestamp, stock_code, action, confidence, rationale,
-            quantity, price, pnl, market, exchange_code
+            quantity, price, pnl, market, exchange_code, selection_context
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             datetime.now(UTC).isoformat(),
@@ -139,6 +160,7 @@ def log_trade(
             pnl,
             market,
             exchange_code,
+            context_json,
         ),
     )
     conn.commit()

src/main.py

@@ -15,6 +15,7 @@ from datetime import UTC, datetime
 from typing import Any
 
 from src.analysis.scanner import MarketScanner
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
 from src.analysis.volatility import VolatilityAnalyzer
 from src.brain.gemini_client import GeminiClient
 from src.broker.kis_api import KISBroker
@@ -29,30 +30,46 @@ from src.db import init_db, log_trade
 from src.logging.decision_logger import DecisionLogger
 from src.logging_config import setup_logging
 from src.markets.schedule import MarketInfo, get_next_market_open, get_open_markets
-from src.notifications.telegram_client import TelegramClient
+from src.notifications.telegram_client import TelegramClient, TelegramCommandHandler
 
 logger = logging.getLogger(__name__)
 
-# Target stock codes to monitor per market
+
-WATCHLISTS = {
+def safe_float(value: str | float | None, default: float = 0.0) -> float:
-    "KR": ["005930", "000660", "035420"],  # Samsung, SK Hynix, NAVER
+    """Convert to float, handling empty strings and None.
-    "US_NASDAQ": ["AAPL", "MSFT", "GOOGL"],  # Example US stocks
+
-    "US_NYSE": ["JPM", "BAC"],  # Example NYSE stocks
+    Args:
-    "JP": ["7203", "6758"],  # Toyota, Sony
+        value: Value to convert (string, float, or None)
-}
+        default: Default value if conversion fails
+
+    Returns:
+        Converted float or default value
+
+    Examples:
+        >>> safe_float("123.45")
+        123.45
+        >>> safe_float("")
+        0.0
+        >>> safe_float(None)
+        0.0
+        >>> safe_float("invalid", 99.0)
+        99.0
+    """
+    if value is None or value == "":
+        return default
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
 
 TRADE_INTERVAL_SECONDS = 60
 SCAN_INTERVAL_SECONDS = 60  # Scan markets every 60 seconds
 MAX_CONNECTION_RETRIES = 3
 
-# Full stock universe per market (for scanning)
+# Daily trading mode constants (for Free tier API efficiency)
-# In production, this would be loaded from a database or API
+DAILY_TRADE_SESSIONS = 4  # Number of trading sessions per day
-STOCK_UNIVERSE = {
+TRADE_SESSION_INTERVAL_HOURS = 6  # Hours between sessions
-    "KR": ["005930", "000660", "035420", "051910", "005380", "005490"],
-    "US_NASDAQ": ["AAPL", "MSFT", "GOOGL", "AMZN", "NVDA", "TSLA"],
-    "US_NYSE": ["JPM", "BAC", "XOM", "JNJ", "V"],
-    "JP": ["7203", "6758", "9984", "6861"],
-}
 
 
 async def trading_cycle(
@@ -67,6 +84,7 @@ async def trading_cycle(
     telegram: TelegramClient,
     market: MarketInfo,
     stock_code: str,
+    scan_candidates: dict[str, ScanCandidate],
 ) -> None:
     """Execute one trading cycle for a single stock."""
     cycle_start_time = asyncio.get_event_loop().time()
@@ -77,16 +95,16 @@ async def trading_cycle(
         balance_data = await broker.get_balance()
 
         output2 = balance_data.get("output2", [{}])
-        total_eval = float(output2[0].get("tot_evlu_amt", "0")) if output2 else 0
+        total_eval = safe_float(output2[0].get("tot_evlu_amt", "0")) if output2 else 0
-        total_cash = float(
+        total_cash = safe_float(
             balance_data.get("output2", [{}])[0].get("dnca_tot_amt", "0")
             if output2
             else "0"
         )
-        purchase_total = float(output2[0].get("pchs_amt_smtl_amt", "0")) if output2 else 0
+        purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0")) if output2 else 0
 
-        current_price = float(orderbook.get("output1", {}).get("stck_prpr", "0"))
+        current_price = safe_float(orderbook.get("output1", {}).get("stck_prpr", "0"))
-        foreigner_net = float(orderbook.get("output1", {}).get("frgn_ntby_qty", "0"))
+        foreigner_net = safe_float(orderbook.get("output1", {}).get("frgn_ntby_qty", "0"))
     else:
         # Overseas market
         price_data = await overseas_broker.get_overseas_price(
@@ -103,11 +121,11 @@ async def trading_cycle(
         else:
             balance_info = {}
 
-        total_eval = float(balance_info.get("frcr_evlu_tota", "0") or "0")
+        total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
-        total_cash = float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
+        total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
-        purchase_total = float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
+        purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
 
-        current_price = float(price_data.get("output", {}).get("last", "0"))
+        current_price = safe_float(price_data.get("output", {}).get("last", "0"))
         foreigner_net = 0.0  # Not available for overseas
 
     # Calculate daily P&L %
@@ -259,7 +277,17 @@ async def trading_cycle(
         except Exception as exc:
             logger.warning("Telegram notification failed: %s", exc)
 
-    # 6. Log trade
+    # 6. Log trade with selection context
+    selection_context = None
+    if stock_code in scan_candidates:
+        candidate = scan_candidates[stock_code]
+        selection_context = {
+            "rsi": candidate.rsi,
+            "volume_ratio": candidate.volume_ratio,
+            "signal": candidate.signal,
+            "score": candidate.score,
+        }
+
     log_trade(
         conn=db_conn,
         stock_code=stock_code,
@@ -268,6 +296,7 @@ async def trading_cycle(
         rationale=decision.rationale,
         market=market.code,
         exchange_code=market.exchange_code,
+        selection_context=selection_context,
     )
 
     # 7. Latency monitoring
@@ -292,6 +321,246 @@ async def trading_cycle(
         )
 
 
+async def run_daily_session(
+    broker: KISBroker,
+    overseas_broker: OverseasBroker,
+    brain: GeminiClient,
+    risk: RiskManager,
+    db_conn: Any,
+    decision_logger: DecisionLogger,
+    context_store: ContextStore,
+    criticality_assessor: CriticalityAssessor,
+    telegram: TelegramClient,
+    settings: Settings,
+    smart_scanner: SmartVolatilityScanner | None = None,
+) -> None:
+    """Execute one daily trading session.
+
+    Designed for API efficiency with Gemini Free tier:
+    - Batch decision making (1 API call per market)
+    - Runs N times per day at fixed intervals
+    - Minimizes API usage while maintaining trading capability
+    """
+    # Get currently open markets
+    open_markets = get_open_markets(settings.enabled_market_list)
+
+    if not open_markets:
+        logger.info("No markets open for this session")
+        return
+
+    logger.info("Starting daily trading session for %d markets", len(open_markets))
+
+    # Process each open market
+    for market in open_markets:
+        # Dynamic stock discovery via scanner (no static watchlists)
+        try:
+            candidates = await smart_scanner.scan()
+            watchlist = [c.stock_code for c in candidates] if candidates else []
+        except Exception as exc:
+            logger.error("Smart Scanner failed for %s: %s", market.name, exc)
+            watchlist = []
+
+        if not watchlist:
+            logger.info("No scanner candidates for market %s — skipping", market.code)
+            continue
+
+        logger.info("Processing market: %s (%d stocks)", market.name, len(watchlist))
+
+        # Collect market data for all stocks from scanner
+        stocks_data = []
+        for stock_code in watchlist:
+            try:
+                if market.is_domestic:
+                    orderbook = await broker.get_orderbook(stock_code)
+                    current_price = safe_float(orderbook.get("output1", {}).get("stck_prpr", "0"))
+                    foreigner_net = safe_float(
+                        orderbook.get("output1", {}).get("frgn_ntby_qty", "0")
+                    )
+                else:
+                    price_data = await overseas_broker.get_overseas_price(
+                        market.exchange_code, stock_code
+                    )
+                    current_price = safe_float(price_data.get("output", {}).get("last", "0"))
+                    foreigner_net = 0.0
+
+                stocks_data.append(
+                    {
+                        "stock_code": stock_code,
+                        "market_name": market.name,
+                        "current_price": current_price,
+                        "foreigner_net": foreigner_net,
+                    }
+                )
+            except Exception as exc:
+                logger.error("Failed to fetch data for %s: %s", stock_code, exc)
+                continue
+
+        if not stocks_data:
+            logger.warning("No valid stock data for market %s", market.code)
+            continue
+
+        # Get batch decisions (1 API call for all stocks in this market)
+        logger.info("Requesting batch decision for %d stocks in %s", len(stocks_data), market.name)
+        decisions = await brain.decide_batch(stocks_data)
+
+        # Get balance data once for the market
+        if market.is_domestic:
+            balance_data = await broker.get_balance()
+            output2 = balance_data.get("output2", [{}])
+            total_eval = safe_float(output2[0].get("tot_evlu_amt", "0")) if output2 else 0
+            total_cash = safe_float(output2[0].get("dnca_tot_amt", "0")) if output2 else 0
+            purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0")) if output2 else 0
+        else:
+            balance_data = await overseas_broker.get_overseas_balance(market.exchange_code)
+            output2 = balance_data.get("output2", [{}])
+            if isinstance(output2, list) and output2:
+                balance_info = output2[0]
+            elif isinstance(output2, dict):
+                balance_info = output2
+            else:
+                balance_info = {}
+
+            total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
+            total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
+            purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
+
+        # Calculate daily P&L %
+        pnl_pct = (
+            ((total_eval - purchase_total) / purchase_total * 100) if purchase_total > 0 else 0.0
+        )
+
+        # Execute decisions for each stock
+        for stock_data in stocks_data:
+            stock_code = stock_data["stock_code"]
+            decision = decisions.get(stock_code)
+
+            if not decision:
+                logger.warning("No decision for %s — skipping", stock_code)
+                continue
+
+            logger.info(
+                "Decision for %s (%s): %s (confidence=%d)",
+                stock_code,
+                market.name,
+                decision.action,
+                decision.confidence,
+            )
+
+            # Log decision
+            context_snapshot = {
+                "L1": {
+                    "current_price": stock_data["current_price"],
+                    "foreigner_net": stock_data["foreigner_net"],
+                },
+                "L2": {
+                    "total_eval": total_eval,
+                    "total_cash": total_cash,
+                    "purchase_total": purchase_total,
+                    "pnl_pct": pnl_pct,
+                },
+            }
+            input_data = {
+                "current_price": stock_data["current_price"],
+                "foreigner_net": stock_data["foreigner_net"],
+                "total_eval": total_eval,
+                "total_cash": total_cash,
+                "pnl_pct": pnl_pct,
+            }
+
+            decision_logger.log_decision(
+                stock_code=stock_code,
+                market=market.code,
+                exchange_code=market.exchange_code,
+                action=decision.action,
+                confidence=decision.confidence,
+                rationale=decision.rationale,
+                context_snapshot=context_snapshot,
+                input_data=input_data,
+            )
+
+            # Execute if actionable
+            if decision.action in ("BUY", "SELL"):
+                quantity = 1
+                order_amount = stock_data["current_price"] * quantity
+
+                # Risk check
+                try:
+                    risk.validate_order(
+                        current_pnl_pct=pnl_pct,
+                        order_amount=order_amount,
+                        total_cash=total_cash,
+                    )
+                except FatFingerRejected as exc:
+                    try:
+                        await telegram.notify_fat_finger(
+                            stock_code=stock_code,
+                            order_amount=exc.order_amount,
+                            total_cash=exc.total_cash,
+                            max_pct=exc.max_pct,
+                        )
+                    except Exception as notify_exc:
+                        logger.warning("Fat finger notification failed: %s", notify_exc)
+                    continue  # Skip this order
+                except CircuitBreakerTripped as exc:
+                    logger.critical("Circuit breaker tripped — stopping session")
+                    try:
+                        await telegram.notify_circuit_breaker(
+                            pnl_pct=exc.pnl_pct,
+                            threshold=exc.threshold,
+                        )
+                    except Exception as notify_exc:
+                        logger.warning("Circuit breaker notification failed: %s", notify_exc)
+                    raise
+
+                # Send order
+                try:
+                    if market.is_domestic:
+                        result = await broker.send_order(
+                            stock_code=stock_code,
+                            order_type=decision.action,
+                            quantity=quantity,
+                            price=0,  # market order
+                        )
+                    else:
+                        result = await overseas_broker.send_overseas_order(
+                            exchange_code=market.exchange_code,
+                            stock_code=stock_code,
+                            order_type=decision.action,
+                            quantity=quantity,
+                            price=0.0,  # market order
+                        )
+                    logger.info("Order result: %s", result.get("msg1", "OK"))
+
+                    # Notify trade execution
+                    try:
+                        await telegram.notify_trade_execution(
+                            stock_code=stock_code,
+                            market=market.name,
+                            action=decision.action,
+                            quantity=quantity,
+                            price=stock_data["current_price"],
+                            confidence=decision.confidence,
+                        )
+                    except Exception as exc:
+                        logger.warning("Telegram notification failed: %s", exc)
+                except Exception as exc:
+                    logger.error("Order execution failed for %s: %s", stock_code, exc)
+                    continue
+
+            # Log trade
+            log_trade(
+                conn=db_conn,
+                stock_code=stock_code,
+                action=decision.action,
+                confidence=decision.confidence,
+                rationale=decision.rationale,
+                market=market.code,
+                exchange_code=market.exchange_code,
+            )
+
+    logger.info("Daily trading session completed")
+
+
 async def run(settings: Settings) -> None:
     """Main async loop — iterate over open markets on a timer."""
     broker = KISBroker(settings)
@@ -309,6 +578,142 @@ async def run(settings: Settings) -> None:
         enabled=settings.TELEGRAM_ENABLED,
     )
 
+    # Initialize Telegram command handler
+    command_handler = TelegramCommandHandler(telegram)
+
+    # Register basic commands
+    async def handle_help() -> None:
+        """Handle /help command."""
+        message = (
+            "<b>📖 Available Commands</b>\n\n"
+            "/help - Show available commands\n"
+            "/status - Trading status (mode, markets, P&L)\n"
+            "/positions - Current holdings\n"
+            "/stop - Pause trading\n"
+            "/resume - Resume trading"
+        )
+        await telegram.send_message(message)
+
+    async def handle_stop() -> None:
+        """Handle /stop command - pause trading."""
+        if not pause_trading.is_set():
+            await telegram.send_message("⏸️ Trading is already paused")
+            return
+
+        pause_trading.clear()
+        logger.info("Trading paused via Telegram command")
+        await telegram.send_message(
+            "<b>⏸️ Trading Paused</b>\n\n"
+            "All trading operations have been suspended.\n"
+            "Use /resume to restart trading."
+        )
+
+    async def handle_resume() -> None:
+        """Handle /resume command - resume trading."""
+        if pause_trading.is_set():
+            await telegram.send_message("▶️ Trading is already active")
+            return
+
+        pause_trading.set()
+        logger.info("Trading resumed via Telegram command")
+        await telegram.send_message(
+            "<b>▶️ Trading Resumed</b>\n\n"
+            "Trading operations have been restarted."
+        )
+
+    async def handle_status() -> None:
+        """Handle /status command - show trading status."""
+        try:
+            # Get trading status
+            trading_status = "Active" if pause_trading.is_set() else "Paused"
+
+            # Calculate P&L from balance data
+            try:
+                balance = await broker.get_balance()
+                output2 = balance.get("output2", [{}])
+                if output2:
+                    total_eval = safe_float(output2[0].get("tot_evlu_amt", "0"))
+                    purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0"))
+                    current_pnl = (
+                        ((total_eval - purchase_total) / purchase_total * 100)
+                        if purchase_total > 0
+                        else 0.0
+                    )
+                    pnl_str = f"{current_pnl:+.2f}%"
+                else:
+                    pnl_str = "N/A"
+            except Exception as exc:
+                logger.warning("Failed to get P&L: %s", exc)
+                pnl_str = "N/A"
+
+            # Format market list
+            markets_str = ", ".join(settings.enabled_market_list)
+
+            message = (
+                "<b>📊 Trading Status</b>\n\n"
+                f"<b>Mode:</b> {settings.MODE.upper()}\n"
+                f"<b>Markets:</b> {markets_str}\n"
+                f"<b>Trading:</b> {trading_status}\n\n"
+                f"<b>Current P&L:</b> {pnl_str}\n"
+                f"<b>Circuit Breaker:</b> {risk._cb_threshold:.1f}%"
+            )
+            await telegram.send_message(message)
+
+        except Exception as exc:
+            logger.error("Error in /status handler: %s", exc)
+            await telegram.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve trading status."
+            )
+
+    async def handle_positions() -> None:
+        """Handle /positions command - show account summary."""
+        try:
+            # Get account balance
+            balance = await broker.get_balance()
+            output2 = balance.get("output2", [{}])
+
+            if not output2:
+                await telegram.send_message(
+                    "<b>💼 Account Summary</b>\n\n"
+                    "No balance information available."
+                )
+                return
+
+            # Extract account-level data
+            total_eval = safe_float(output2[0].get("tot_evlu_amt", "0"))
+            total_cash = safe_float(output2[0].get("dnca_tot_amt", "0"))
+            purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0"))
+
+            # Calculate P&L
+            pnl_pct = (
+                ((total_eval - purchase_total) / purchase_total * 100)
+                if purchase_total > 0
+                else 0.0
+            )
+            pnl_sign = "+" if pnl_pct >= 0 else ""
+
+            message = (
+                "<b>💼 Account Summary</b>\n\n"
+                f"<b>Total Evaluation:</b> ₩{total_eval:,.0f}\n"
+                f"<b>Available Cash:</b> ₩{total_cash:,.0f}\n"
+                f"<b>Purchase Total:</b> ₩{purchase_total:,.0f}\n"
+                f"<b>P&L:</b> {pnl_sign}{pnl_pct:.2f}%\n\n"
+                "<i>Note: Individual position details require API enhancement</i>"
+            )
+            await telegram.send_message(message)
+
+        except Exception as exc:
+            logger.error("Error in /positions handler: %s", exc)
+            await telegram.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve positions."
+            )
+
+    command_handler.register_command("help", handle_help)
+    command_handler.register_command("stop", handle_stop)
+    command_handler.register_command("resume", handle_resume)
+    command_handler.register_command("status", handle_status)
+    command_handler.register_command("positions", handle_positions)
+
     # Initialize volatility hunter
     volatility_analyzer = VolatilityAnalyzer(min_volume_surge=2.0, min_price_change=1.0)
     market_scanner = MarketScanner(
@@ -317,8 +722,22 @@ async def run(settings: Settings) -> None:
         volatility_analyzer=volatility_analyzer,
         context_store=context_store,
         top_n=5,
+        max_concurrent_scans=1,  # Fully serialized to avoid EGW00201
     )
 
+    # Initialize smart scanner (Python-first, AI-last pipeline)
+    smart_scanner = SmartVolatilityScanner(
+        broker=broker,
+        volatility_analyzer=volatility_analyzer,
+        settings=settings,
+    )
+
+    # Track scan candidates for selection context logging
+    scan_candidates: dict[str, ScanCandidate] = {}  # stock_code -> candidate
+
+    # Active stocks per market (dynamically discovered by scanner)
+    active_stocks: dict[str, list[str]] = {}  # market_code -> [stock_codes]
+
     # Initialize latency control system
     criticality_assessor = CriticalityAssessor(
         critical_pnl_threshold=-2.5,  # Near circuit breaker at -3.0%
@@ -335,7 +754,10 @@ async def run(settings: Settings) -> None:
     # Track market open/close state for notifications
     _market_states: dict[str, bool] = {}  # market_code -> is_open
 
+    # Trading control events
     shutdown = asyncio.Event()
+    pause_trading = asyncio.Event()
+    pause_trading.set()  # Default: trading enabled
 
     def _signal_handler() -> None:
         logger.info("Shutdown signal received")
@@ -345,7 +767,7 @@ async def run(settings: Settings) -> None:
     for sig in (signal.SIGINT, signal.SIGTERM):
         loop.add_signal_handler(sig, _signal_handler)
 
-    logger.info("The Ouroboros is alive. Mode: %s", settings.MODE)
+    logger.info("The Ouroboros is alive. Mode: %s, Trading: %s", settings.MODE, settings.TRADE_MODE)
     logger.info("Enabled markets: %s", settings.enabled_market_list)
 
     # Notify system startup
@@ -354,173 +776,236 @@ async def run(settings: Settings) -> None:
     except Exception as exc:
         logger.warning("System startup notification failed: %s", exc)
 
+    # Start command handler
     try:
-        while not shutdown.is_set():
+        await command_handler.start_polling()
-            # Get currently open markets
+    except Exception as exc:
-            open_markets = get_open_markets(settings.enabled_market_list)
+        logger.warning("Failed to start command handler: %s", exc)
 
-            if not open_markets:
+    try:
-                # Notify market close for any markets that were open
+        # Branch based on trading mode
-                for market_code, is_open in list(_market_states.items()):
+        if settings.TRADE_MODE == "daily":
-                    if is_open:
+            # Daily trading mode: batch decisions at fixed intervals
-                        try:
+            logger.info(
-                            from src.markets.schedule import MARKETS
+                "Daily trading mode: %d sessions every %d hours",
+                settings.DAILY_SESSIONS,
+                settings.SESSION_INTERVAL_HOURS,
+            )
 
-                            market_info = MARKETS.get(market_code)
+            session_interval = settings.SESSION_INTERVAL_HOURS * 3600  # Convert to seconds
-                            if market_info:
+
-                                await telegram.notify_market_close(market_info.name, 0.0)
+            while not shutdown.is_set():
-                        except Exception as exc:
+                # Wait for trading to be unpaused
-                            logger.warning("Market close notification failed: %s", exc)
+                await pause_trading.wait()
-                        _market_states[market_code] = False
 
-                # No markets open — wait until next market opens
                 try:
-                    next_market, next_open_time = get_next_market_open(
+                    await run_daily_session(
-                        settings.enabled_market_list
+                        broker,
+                        overseas_broker,
+                        brain,
+                        risk,
+                        db_conn,
+                        decision_logger,
+                        context_store,
+                        criticality_assessor,
+                        telegram,
+                        settings,
+                        smart_scanner=smart_scanner,
                     )
-                    now = datetime.now(UTC)
+                except CircuitBreakerTripped:
-                    wait_seconds = (next_open_time - now).total_seconds()
+                    logger.critical("Circuit breaker tripped — shutting down")
-                    logger.info(
+                    shutdown.set()
-                        "No markets open. Next market: %s, opens in %.1f hours",
-                        next_market.name,
-                        wait_seconds / 3600,
-                    )
-                    await asyncio.wait_for(shutdown.wait(), timeout=wait_seconds)
-                except TimeoutError:
-                    continue  # Market should be open now
-                except ValueError as exc:
-                    logger.error("Failed to find next market open: %s", exc)
-                    await asyncio.sleep(TRADE_INTERVAL_SECONDS)
-                continue
-
-            # Process each open market
-            for market in open_markets:
-                if shutdown.is_set():
                     break
+                except Exception as exc:
+                    logger.exception("Daily session error: %s", exc)
 
-                # Notify market open if it just opened
+                # Wait for next session or shutdown
-                if not _market_states.get(market.code, False):
+                logger.info("Next session in %.1f hours", session_interval / 3600)
+                try:
+                    await asyncio.wait_for(shutdown.wait(), timeout=session_interval)
+                except TimeoutError:
+                    pass  # Normal — time for next session
+
+        else:
+            # Realtime trading mode: original per-stock loop
+            logger.info("Realtime trading mode: 60s interval per stock")
+
+            while not shutdown.is_set():
+                # Wait for trading to be unpaused
+                await pause_trading.wait()
+
+                # Get currently open markets
+                open_markets = get_open_markets(settings.enabled_market_list)
+
+                if not open_markets:
+                    # Notify market close for any markets that were open
+                    for market_code, is_open in list(_market_states.items()):
+                        if is_open:
+                            try:
+                                from src.markets.schedule import MARKETS
+
+                                market_info = MARKETS.get(market_code)
+                                if market_info:
+                                    await telegram.notify_market_close(market_info.name, 0.0)
+                            except Exception as exc:
+                                logger.warning("Market close notification failed: %s", exc)
+                            _market_states[market_code] = False
+
+                    # No markets open — wait until next market opens
                     try:
-                        await telegram.notify_market_open(market.name)
+                        next_market, next_open_time = get_next_market_open(
-                    except Exception as exc:
+                            settings.enabled_market_list
-                        logger.warning("Market open notification failed: %s", exc)
+                        )
-                    _market_states[market.code] = True
+                        now = datetime.now(UTC)
-
+                        wait_seconds = (next_open_time - now).total_seconds()
-                # Volatility Hunter: Scan market periodically to update watchlist
+                        logger.info(
-                now_timestamp = asyncio.get_event_loop().time()
+                            "No markets open. Next market: %s, opens in %.1f hours",
-                last_scan = last_scan_time.get(market.code, 0.0)
+                            next_market.name,
-                if now_timestamp - last_scan >= SCAN_INTERVAL_SECONDS:
+                            wait_seconds / 3600,
-                    try:
+                        )
-                        # Scan all stocks in the universe
+                        await asyncio.wait_for(shutdown.wait(), timeout=wait_seconds)
-                        stock_universe = STOCK_UNIVERSE.get(market.code, [])
+                    except TimeoutError:
-                        if stock_universe:
+                        continue  # Market should be open now
-                            logger.info("Volatility Hunter: Scanning %s market", market.name)
+                    except ValueError as exc:
-                            scan_result = await market_scanner.scan_market(
+                        logger.error("Failed to find next market open: %s", exc)
-                                market, stock_universe
+                        await asyncio.sleep(TRADE_INTERVAL_SECONDS)
-                            )
-
-                            # Update watchlist with top movers
-                            current_watchlist = WATCHLISTS.get(market.code, [])
-                            updated_watchlist = market_scanner.get_updated_watchlist(
-                                current_watchlist,
-                                scan_result,
-                                max_replacements=2,
-                            )
-                            WATCHLISTS[market.code] = updated_watchlist
-
-                            logger.info(
-                                "Volatility Hunter: Watchlist updated for %s (%d top movers, %d breakouts)",
-                                market.name,
-                                len(scan_result.top_movers),
-                                len(scan_result.breakouts),
-                            )
-
-                        last_scan_time[market.code] = now_timestamp
-                    except Exception as exc:
-                        logger.error("Volatility Hunter scan failed for %s: %s", market.name, exc)
-
-                # Get watchlist for this market
-                watchlist = WATCHLISTS.get(market.code, [])
-                if not watchlist:
-                    logger.debug("No watchlist for market %s", market.code)
                     continue
 
-                logger.info("Processing market: %s (%d stocks)", market.name, len(watchlist))
+                # Process each open market
-
+                for market in open_markets:
-                # Process each stock in the watchlist
-                for stock_code in watchlist:
                     if shutdown.is_set():
                         break
 
-                    # Retry logic for connection errors
+                    # Notify market open if it just opened
-                    for attempt in range(1, MAX_CONNECTION_RETRIES + 1):
+                    if not _market_states.get(market.code, False):
                         try:
-                            await trading_cycle(
+                            await telegram.notify_market_open(market.name)
-                                broker,
-                                overseas_broker,
-                                brain,
-                                risk,
-                                db_conn,
-                                decision_logger,
-                                context_store,
-                                criticality_assessor,
-                                telegram,
-                                market,
-                                stock_code,
-                            )
-                            break  # Success — exit retry loop
-                        except CircuitBreakerTripped as exc:
-                            logger.critical("Circuit breaker tripped — shutting down")
-                            try:
-                                await telegram.notify_circuit_breaker(
-                                    pnl_pct=exc.pnl_pct,
-                                    threshold=exc.threshold,
-                                )
-                            except Exception as notify_exc:
-                                logger.warning(
-                                    "Circuit breaker notification failed: %s", notify_exc
-                                )
-                            raise
-                        except ConnectionError as exc:
-                            if attempt < MAX_CONNECTION_RETRIES:
-                                logger.warning(
-                                    "Connection error for %s (attempt %d/%d): %s",
-                                    stock_code,
-                                    attempt,
-                                    MAX_CONNECTION_RETRIES,
-                                    exc,
-                                )
-                                await asyncio.sleep(2**attempt)  # Exponential backoff
-                            else:
-                                logger.error(
-                                    "Connection error for %s (all retries exhausted): %s",
-                                    stock_code,
-                                    exc,
-                                )
-                                break  # Give up on this stock
                         except Exception as exc:
-                            logger.exception("Unexpected error for %s: %s", stock_code, exc)
+                            logger.warning("Market open notification failed: %s", exc)
-                            break  # Don't retry on unexpected errors
+                        _market_states[market.code] = True
 
-            # Log priority queue metrics periodically
+                    # Smart Scanner: dynamic stock discovery (no static watchlists)
-            metrics = await priority_queue.get_metrics()
+                    now_timestamp = asyncio.get_event_loop().time()
-            if metrics.total_enqueued > 0:
+                    last_scan = last_scan_time.get(market.code, 0.0)
-                logger.info(
+                    if now_timestamp - last_scan >= SCAN_INTERVAL_SECONDS:
-                    "Priority queue metrics: enqueued=%d, dequeued=%d, size=%d, timeouts=%d, errors=%d",
+                        try:
-                    metrics.total_enqueued,
+                            logger.info("Smart Scanner: Scanning %s market", market.name)
-                    metrics.total_dequeued,
-                    metrics.current_size,
-                    metrics.total_timeouts,
-                    metrics.total_errors,
-                )
 
-            # Wait for next cycle or shutdown
+                            candidates = await smart_scanner.scan()
-            try:
+
-                await asyncio.wait_for(shutdown.wait(), timeout=TRADE_INTERVAL_SECONDS)
+                            if candidates:
-            except TimeoutError:
+                                # Use scanner results directly as trading candidates
-                pass  # Normal — timeout means it's time for next cycle
+                                active_stocks[market.code] = smart_scanner.get_stock_codes(
+                                    candidates
+                                )
+
+                                # Store candidates for selection context logging
+                                for candidate in candidates:
+                                    scan_candidates[candidate.stock_code] = candidate
+
+                                logger.info(
+                                    "Smart Scanner: Found %d candidates for %s: %s",
+                                    len(candidates),
+                                    market.name,
+                                    [f"{c.stock_code}(RSI={c.rsi:.0f})" for c in candidates],
+                                )
+                            else:
+                                logger.info(
+                                    "Smart Scanner: No candidates for %s — no trades", market.name
+                                )
+                                active_stocks[market.code] = []
+
+                            last_scan_time[market.code] = now_timestamp
+
+                        except Exception as exc:
+                            logger.error("Smart Scanner failed for %s: %s", market.name, exc)
+
+                    # Get active stocks from scanner (dynamic, no static fallback)
+                    stock_codes = active_stocks.get(market.code, [])
+                    if not stock_codes:
+                        logger.debug("No active stocks for market %s", market.code)
+                        continue
+
+                    logger.info("Processing market: %s (%d stocks)", market.name, len(stock_codes))
+
+                    # Process each stock from scanner results
+                    for stock_code in stock_codes:
+                        if shutdown.is_set():
+                            break
+
+                        # Retry logic for connection errors
+                        for attempt in range(1, MAX_CONNECTION_RETRIES + 1):
+                            try:
+                                await trading_cycle(
+                                    broker,
+                                    overseas_broker,
+                                    brain,
+                                    risk,
+                                    db_conn,
+                                    decision_logger,
+                                    context_store,
+                                    criticality_assessor,
+                                    telegram,
+                                    market,
+                                    stock_code,
+                                    scan_candidates,
+                                )
+                                break  # Success — exit retry loop
+                            except CircuitBreakerTripped as exc:
+                                logger.critical("Circuit breaker tripped — shutting down")
+                                try:
+                                    await telegram.notify_circuit_breaker(
+                                        pnl_pct=exc.pnl_pct,
+                                        threshold=exc.threshold,
+                                    )
+                                except Exception as notify_exc:
+                                    logger.warning(
+                                        "Circuit breaker notification failed: %s", notify_exc
+                                    )
+                                raise
+                            except ConnectionError as exc:
+                                if attempt < MAX_CONNECTION_RETRIES:
+                                    logger.warning(
+                                        "Connection error for %s (attempt %d/%d): %s",
+                                        stock_code,
+                                        attempt,
+                                        MAX_CONNECTION_RETRIES,
+                                        exc,
+                                    )
+                                    await asyncio.sleep(2**attempt)  # Exponential backoff
+                                else:
+                                    logger.error(
+                                        "Connection error for %s (all retries exhausted): %s",
+                                        stock_code,
+                                        exc,
+                                    )
+                                    break  # Give up on this stock
+                            except Exception as exc:
+                                logger.exception("Unexpected error for %s: %s", stock_code, exc)
+                                break  # Don't retry on unexpected errors
+
+                # Log priority queue metrics periodically
+                metrics = await priority_queue.get_metrics()
+                if metrics.total_enqueued > 0:
+                    logger.info(
+                        "Priority queue metrics: enqueued=%d, dequeued=%d, size=%d, timeouts=%d, errors=%d",
+                        metrics.total_enqueued,
+                        metrics.total_dequeued,
+                        metrics.current_size,
+                        metrics.total_timeouts,
+                        metrics.total_errors,
+                    )
+
+                # Wait for next cycle or shutdown
+                try:
+                    await asyncio.wait_for(shutdown.wait(), timeout=TRADE_INTERVAL_SECONDS)
+                except TimeoutError:
+                    pass  # Normal — timeout means it's time for next cycle
     finally:
+        # Clean up resources
+        await command_handler.stop_polling()
         await broker.close()
+        await telegram.close()
         db_conn.close()
         logger.info("The Ouroboros rests.")
 

src/notifications/README.md

@@ -200,14 +200,151 @@ telegram = TelegramClient(
 )
 ```
 
+## Bidirectional Commands
+
+Control your trading bot remotely via Telegram commands. The bot not only sends notifications but also accepts commands for real-time control.
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Welcome message with quick start guide |
+| `/help` | List all available commands |
+| `/status` | Current trading status (mode, markets, P&L, circuit breaker) |
+| `/positions` | View current holdings grouped by market |
+| `/stop` | Pause all trading operations |
+| `/resume` | Resume trading operations |
+
+### Command Examples
+
+**Check Trading Status**
+```
+You: /status
+
+Bot:
+📊 Trading Status
+
+Mode: PAPER
+Markets: Korea, United States
+Trading: Active
+
+Current P&L: +2.50%
+Circuit Breaker: -3.0%
+```
+
+**View Holdings**
+```
+You: /positions
+
+Bot:
+💼 Current Holdings
+
+🇰🇷 Korea
+• 005930: 10 shares @ 70,000
+• 035420: 5 shares @ 200,000
+
+🇺🇸 Overseas
+• AAPL: 15 shares @ 175
+• TSLA: 8 shares @ 245
+
+Cash: ₩5,000,000
+```
+
+**Pause Trading**
+```
+You: /stop
+
+Bot:
+⏸️ Trading Paused
+
+All trading operations have been suspended.
+Use /resume to restart trading.
+```
+
+**Resume Trading**
+```
+You: /resume
+
+Bot:
+▶️ Trading Resumed
+
+Trading operations have been restarted.
+```
+
+### Security
+
+**Chat ID Verification**
+- Commands are only accepted from the configured `TELEGRAM_CHAT_ID`
+- Unauthorized users receive no response
+- Command attempts from wrong chat IDs are logged
+
+**Authorization Required**
+- Only the bot owner (chat ID in `.env`) can control trading
+- No way for unauthorized users to discover or use commands
+- All command executions are logged for audit
+
+### Configuration
+
+Add to your `.env` file:
+
+```bash
+# Commands are enabled by default
+TELEGRAM_COMMANDS_ENABLED=true
+
+# Polling interval (seconds) - how often to check for commands
+TELEGRAM_POLLING_INTERVAL=1.0
+```
+
+To disable commands but keep notifications:
+```bash
+TELEGRAM_COMMANDS_ENABLED=false
+```
+
+### How It Works
+
+1. **Long Polling**: Bot checks Telegram API every second for new messages
+2. **Command Parsing**: Messages starting with `/` are parsed as commands
+3. **Authentication**: Chat ID is verified before executing any command
+4. **Execution**: Command handler is called with current bot state
+5. **Response**: Result is sent back via Telegram
+
+### Error Handling
+
+- Command parsing errors → "Unknown command" response
+- API failures → Graceful degradation, error logged
+- Invalid state → Appropriate message (e.g., "Trading is already paused")
+- Trading loop isolation → Command errors never crash trading
+
+### Troubleshooting Commands
+
+**Commands not responding**
+1. Check `TELEGRAM_COMMANDS_ENABLED=true` in `.env`
+2. Verify you started conversation with `/start`
+3. Check logs for command handler errors
+4. Confirm chat ID matches `.env` configuration
+
+**Wrong chat ID**
+- Commands from unauthorized chats are silently ignored
+- Check logs for "unauthorized chat_id" warnings
+
+**Delayed responses**
+- Polling interval is 1 second by default
+- Network latency may add delay
+- Check `TELEGRAM_POLLING_INTERVAL` setting
+
 ## API Reference
 
 See `telegram_client.py` for full API documentation.
 
-Key methods:
+### Notification Methods
 - `notify_trade_execution()` - Trade alerts
 - `notify_circuit_breaker()` - Emergency stops
 - `notify_fat_finger()` - Order rejections
 - `notify_market_open/close()` - Session tracking
 - `notify_system_start/shutdown()` - Lifecycle events
 - `notify_error()` - Error alerts
+
+### Command Handler
+- `TelegramCommandHandler` - Bidirectional command processing
+- `register_command()` - Register custom command handlers
+- `start_polling()` / `stop_polling()` - Lifecycle management

src/notifications/telegram_client.py

@@ -3,6 +3,7 @@
 import asyncio
 import logging
 import time
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
 
@@ -117,26 +118,28 @@ class TelegramClient:
         if self._session is not None and not self._session.closed:
             await self._session.close()
 
-    async def _send_notification(self, msg: NotificationMessage) -> None:
+    async def send_message(self, text: str, parse_mode: str = "HTML") -> bool:
         """
-        Send notification to Telegram with graceful degradation.
+        Send a generic text message to Telegram.
 
         Args:
-            msg: Notification message to send
+            text: Message text to send
+            parse_mode: Parse mode for formatting (HTML or Markdown)
+
+        Returns:
+            True if message was sent successfully, False otherwise
         """
         if not self._enabled:
-            return
+            return False
 
         try:
             await self._rate_limiter.acquire()
 
-            formatted_message = f"{msg.priority.emoji} {msg.message}"
             url = f"{self.API_BASE.format(token=self._bot_token)}/sendMessage"
-
             payload = {
                 "chat_id": self._chat_id,
-                "text": formatted_message,
+                "text": text,
-                "parse_mode": "HTML",
+                "parse_mode": parse_mode,
             }
 
             session = self._get_session()
@@ -146,15 +149,29 @@ class TelegramClient:
                     logger.error(
                         "Telegram API error (status=%d): %s", resp.status, error_text
                     )
-                else:
+                    return False
-                    logger.debug("Telegram notification sent: %s", msg.message[:50])
+                logger.debug("Telegram message sent: %s", text[:50])
+                return True
 
         except asyncio.TimeoutError:
-            logger.error("Telegram notification timeout")
+            logger.error("Telegram message timeout")
+            return False
         except aiohttp.ClientError as exc:
-            logger.error("Telegram notification failed: %s", exc)
+            logger.error("Telegram message failed: %s", exc)
+            return False
         except Exception as exc:
-            logger.error("Unexpected error sending notification: %s", exc)
+            logger.error("Unexpected error sending message: %s", exc)
+            return False
+
+    async def _send_notification(self, msg: NotificationMessage) -> None:
+        """
+        Send notification to Telegram with graceful degradation.
+
+        Args:
+            msg: Notification message to send
+        """
+        formatted_message = f"{msg.priority.emoji} {msg.message}"
+        await self.send_message(formatted_message)
 
     async def notify_trade_execution(
         self,
@@ -323,3 +340,172 @@ class TelegramClient:
         await self._send_notification(
             NotificationMessage(priority=NotificationPriority.HIGH, message=message)
         )
+
+
+class TelegramCommandHandler:
+    """Handles incoming Telegram commands via long polling."""
+
+    def __init__(
+        self, client: TelegramClient, polling_interval: float = 1.0
+    ) -> None:
+        """
+        Initialize command handler.
+
+        Args:
+            client: TelegramClient instance for sending responses
+            polling_interval: Polling interval in seconds
+        """
+        self._client = client
+        self._polling_interval = polling_interval
+        self._commands: dict[str, Callable[[], Awaitable[None]]] = {}
+        self._last_update_id = 0
+        self._polling_task: asyncio.Task[None] | None = None
+        self._running = False
+
+    def register_command(
+        self, command: str, handler: Callable[[], Awaitable[None]]
+    ) -> None:
+        """
+        Register a command handler.
+
+        Args:
+            command: Command name (without leading slash, e.g., "start")
+            handler: Async function to handle the command
+        """
+        self._commands[command] = handler
+        logger.debug("Registered command handler: /%s", command)
+
+    async def start_polling(self) -> None:
+        """Start long polling for commands."""
+        if self._running:
+            logger.warning("Command handler already running")
+            return
+
+        if not self._client._enabled:
+            logger.info("Command handler disabled (TelegramClient disabled)")
+            return
+
+        self._running = True
+        self._polling_task = asyncio.create_task(self._poll_loop())
+        logger.info("Started Telegram command polling")
+
+    async def stop_polling(self) -> None:
+        """Stop polling and cancel pending tasks."""
+        if not self._running:
+            return
+
+        self._running = False
+        if self._polling_task:
+            self._polling_task.cancel()
+            try:
+                await self._polling_task
+            except asyncio.CancelledError:
+                pass
+        logger.info("Stopped Telegram command polling")
+
+    async def _poll_loop(self) -> None:
+        """Main polling loop that fetches updates."""
+        while self._running:
+            try:
+                updates = await self._get_updates()
+                for update in updates:
+                    await self._handle_update(update)
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.error("Error in polling loop: %s", exc)
+
+            await asyncio.sleep(self._polling_interval)
+
+    async def _get_updates(self) -> list[dict]:
+        """
+        Fetch updates from Telegram API.
+
+        Returns:
+            List of update objects
+        """
+        try:
+            url = f"{self._client.API_BASE.format(token=self._client._bot_token)}/getUpdates"
+            payload = {
+                "offset": self._last_update_id + 1,
+                "timeout": int(self._polling_interval),
+                "allowed_updates": ["message"],
+            }
+
+            session = self._client._get_session()
+            async with session.post(url, json=payload) as resp:
+                if resp.status != 200:
+                    error_text = await resp.text()
+                    logger.error(
+                        "getUpdates API error (status=%d): %s", resp.status, error_text
+                    )
+                    return []
+
+                data = await resp.json()
+                if not data.get("ok"):
+                    logger.error("getUpdates returned ok=false: %s", data)
+                    return []
+
+                updates = data.get("result", [])
+                if updates:
+                    self._last_update_id = updates[-1]["update_id"]
+
+                return updates
+
+        except asyncio.TimeoutError:
+            logger.debug("getUpdates timeout (normal)")
+            return []
+        except aiohttp.ClientError as exc:
+            logger.error("getUpdates failed: %s", exc)
+            return []
+        except Exception as exc:
+            logger.error("Unexpected error in _get_updates: %s", exc)
+            return []
+
+    async def _handle_update(self, update: dict) -> None:
+        """
+        Parse and handle a single update.
+
+        Args:
+            update: Update object from Telegram API
+        """
+        try:
+            message = update.get("message")
+            if not message:
+                return
+
+            # Verify chat_id matches configured chat
+            chat_id = str(message.get("chat", {}).get("id", ""))
+            if chat_id != self._client._chat_id:
+                logger.warning(
+                    "Ignoring command from unauthorized chat_id: %s", chat_id
+                )
+                return
+
+            # Extract command text
+            text = message.get("text", "").strip()
+            if not text.startswith("/"):
+                return
+
+            # Parse command (remove leading slash and extract command name)
+            command_parts = text[1:].split()
+            if not command_parts:
+                return
+
+            # Remove @botname suffix if present (for group chats)
+            command_name = command_parts[0].split("@")[0]
+
+            # Execute handler
+            handler = self._commands.get(command_name)
+            if handler:
+                logger.info("Executing command: /%s", command_name)
+                await handler()
+            else:
+                logger.debug("Unknown command: /%s", command_name)
+                await self._client.send_message(
+                    f"Unknown command: /{command_name}\nUse /help to see available commands."
+                )
+
+        except Exception as exc:
+            logger.error("Error handling update: %s", exc)
+            # Don't crash the polling loop on handler errors

src/strategy/models.py

@@ -0,0 +1,164 @@
+"""Pydantic models for pre-market scenario planning.
+
+Defines the data contracts for the proactive strategy system:
+- AI generates DayPlaybook before market open (structured JSON scenarios)
+- Local ScenarioEngine matches conditions during market hours (no API calls)
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ScenarioAction(str, Enum):
+    """Actions that can be taken by scenarios."""
+
+    BUY = "BUY"
+    SELL = "SELL"
+    HOLD = "HOLD"
+    REDUCE_ALL = "REDUCE_ALL"
+
+
+class MarketOutlook(str, Enum):
+    """AI's assessment of market direction."""
+
+    BULLISH = "bullish"
+    NEUTRAL_TO_BULLISH = "neutral_to_bullish"
+    NEUTRAL = "neutral"
+    NEUTRAL_TO_BEARISH = "neutral_to_bearish"
+    BEARISH = "bearish"
+
+
+class PlaybookStatus(str, Enum):
+    """Lifecycle status of a playbook."""
+
+    PENDING = "pending"
+    READY = "ready"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class StockCondition(BaseModel):
+    """Condition fields for scenario matching (all optional, AND-combined).
+
+    The ScenarioEngine evaluates all non-None fields as AND conditions.
+    A condition matches only if ALL specified fields are satisfied.
+    """
+
+    rsi_below: float | None = None
+    rsi_above: float | None = None
+    volume_ratio_above: float | None = None
+    volume_ratio_below: float | None = None
+    price_above: float | None = None
+    price_below: float | None = None
+    price_change_pct_above: float | None = None
+    price_change_pct_below: float | None = None
+
+    def has_any_condition(self) -> bool:
+        """Check if at least one condition field is set."""
+        return any(
+            v is not None
+            for v in (
+                self.rsi_below,
+                self.rsi_above,
+                self.volume_ratio_above,
+                self.volume_ratio_below,
+                self.price_above,
+                self.price_below,
+                self.price_change_pct_above,
+                self.price_change_pct_below,
+            )
+        )
+
+
+class StockScenario(BaseModel):
+    """A single condition-action rule for one stock."""
+
+    condition: StockCondition
+    action: ScenarioAction
+    confidence: int = Field(ge=0, le=100)
+    allocation_pct: float = Field(ge=0, le=100, default=10.0)
+    stop_loss_pct: float = Field(le=0, default=-2.0)
+    take_profit_pct: float = Field(ge=0, default=3.0)
+    rationale: str = ""
+
+
+class StockPlaybook(BaseModel):
+    """All scenarios for a single stock (ordered by priority)."""
+
+    stock_code: str
+    stock_name: str = ""
+    scenarios: list[StockScenario] = Field(min_length=1)
+
+
+class GlobalRule(BaseModel):
+    """Portfolio-level rule (checked before stock-level scenarios)."""
+
+    condition: str  # e.g. "portfolio_pnl_pct < -2.0"
+    action: ScenarioAction
+    rationale: str = ""
+
+
+class CrossMarketContext(BaseModel):
+    """Summary of another market's state for cross-market awareness."""
+
+    market: str  # e.g. "US" or "KR"
+    date: str
+    total_pnl: float = 0.0
+    win_rate: float = 0.0
+    index_change_pct: float = 0.0  # e.g. KOSPI or S&P500 change
+    key_events: list[str] = Field(default_factory=list)
+    lessons: list[str] = Field(default_factory=list)
+
+
+class DayPlaybook(BaseModel):
+    """Complete playbook for a single trading day in a single market.
+
+    Generated by PreMarketPlanner (1 Gemini call per market per day).
+    Consumed by ScenarioEngine during market hours (0 API calls).
+    """
+
+    date: date
+    market: str  # "KR" or "US"
+    market_outlook: MarketOutlook = MarketOutlook.NEUTRAL
+    generated_at: str = ""  # ISO timestamp
+    gemini_model: str = ""
+    token_count: int = 0
+    global_rules: list[GlobalRule] = Field(default_factory=list)
+    stock_playbooks: list[StockPlaybook] = Field(default_factory=list)
+    default_action: ScenarioAction = ScenarioAction.HOLD
+    context_summary: dict = Field(default_factory=dict)
+    cross_market: CrossMarketContext | None = None
+
+    @field_validator("stock_playbooks")
+    @classmethod
+    def validate_unique_stocks(cls, v: list[StockPlaybook]) -> list[StockPlaybook]:
+        codes = [pb.stock_code for pb in v]
+        if len(codes) != len(set(codes)):
+            raise ValueError("Duplicate stock codes in playbook")
+        return v
+
+    def get_stock_playbook(self, stock_code: str) -> StockPlaybook | None:
+        """Find the playbook for a specific stock."""
+        for pb in self.stock_playbooks:
+            if pb.stock_code == stock_code:
+                return pb
+        return None
+
+    @property
+    def scenario_count(self) -> int:
+        """Total number of scenarios across all stocks."""
+        return sum(len(pb.scenarios) for pb in self.stock_playbooks)
+
+    @property
+    def stock_count(self) -> int:
+        """Number of stocks with scenarios."""
+        return len(self.stock_playbooks)
+
+    def model_post_init(self, __context: object) -> None:
+        """Set generated_at if not provided."""
+        if not self.generated_at:
+            self.generated_at = datetime.now(UTC).isoformat()

tests/test_brain.py

@@ -152,3 +152,121 @@ class TestPromptConstruction:
         assert "JSON" in prompt
         assert "action" in prompt
         assert "confidence" in prompt
+
+
+# ---------------------------------------------------------------------------
+# Batch Decision Making
+# ---------------------------------------------------------------------------
+
+
+class TestBatchDecisionParsing:
+    """Batch response parser must handle JSON arrays correctly."""
+
+    def test_parse_valid_batch_response(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [
+            {"stock_code": "AAPL", "current_price": 185.5},
+            {"stock_code": "MSFT", "current_price": 420.0},
+        ]
+        raw = """[
+            {"code": "AAPL", "action": "BUY", "confidence": 85, "rationale": "Strong momentum"},
+            {"code": "MSFT", "action": "HOLD", "confidence": 50, "rationale": "Wait for earnings"}
+        ]"""
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert len(decisions) == 2
+        assert decisions["AAPL"].action == "BUY"
+        assert decisions["AAPL"].confidence == 85
+        assert decisions["MSFT"].action == "HOLD"
+        assert decisions["MSFT"].confidence == 50
+
+    def test_parse_batch_with_markdown_wrapper(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = """```json
+[{"code": "AAPL", "action": "BUY", "confidence": 90, "rationale": "Good"}]
+```"""
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "BUY"
+        assert decisions["AAPL"].confidence == 90
+
+    def test_parse_batch_empty_response_returns_hold_for_all(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [
+            {"stock_code": "AAPL", "current_price": 185.5},
+            {"stock_code": "MSFT", "current_price": 420.0},
+        ]
+
+        decisions = client._parse_batch_response("", stocks_data, token_count=100)
+
+        assert len(decisions) == 2
+        assert decisions["AAPL"].action == "HOLD"
+        assert decisions["AAPL"].confidence == 0
+        assert decisions["MSFT"].action == "HOLD"
+
+    def test_parse_batch_malformed_json_returns_hold_for_all(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = "This is not JSON"
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "HOLD"
+        assert decisions["AAPL"].confidence == 0
+
+    def test_parse_batch_not_array_returns_hold_for_all(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = '{"code": "AAPL", "action": "BUY", "confidence": 90, "rationale": "Good"}'
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "HOLD"
+        assert decisions["AAPL"].confidence == 0
+
+    def test_parse_batch_missing_stock_gets_hold(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [
+            {"stock_code": "AAPL", "current_price": 185.5},
+            {"stock_code": "MSFT", "current_price": 420.0},
+        ]
+        # Response only has AAPL, MSFT is missing
+        raw = '[{"code": "AAPL", "action": "BUY", "confidence": 85, "rationale": "Good"}]'
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "BUY"
+        assert decisions["MSFT"].action == "HOLD"
+        assert decisions["MSFT"].confidence == 0
+
+    def test_parse_batch_invalid_action_becomes_hold(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = '[{"code": "AAPL", "action": "YOLO", "confidence": 90, "rationale": "Moon"}]'
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "HOLD"
+
+    def test_parse_batch_low_confidence_becomes_hold(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = '[{"code": "AAPL", "action": "BUY", "confidence": 65, "rationale": "Weak"}]'
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "HOLD"
+        assert decisions["AAPL"].confidence == 65
+
+    def test_parse_batch_missing_fields_gets_hold(self, settings):
+        client = GeminiClient(settings)
+        stocks_data = [{"stock_code": "AAPL", "current_price": 185.5}]
+        raw = '[{"code": "AAPL", "action": "BUY"}]'  # Missing confidence and rationale
+
+        decisions = client._parse_batch_response(raw, stocks_data, token_count=100)
+
+        assert decisions["AAPL"].action == "HOLD"
+        assert decisions["AAPL"].confidence == 0

tests/test_broker.py

@@ -89,6 +89,70 @@ class TestTokenManagement:
 
         await broker.close()
 
+    @pytest.mark.asyncio
+    async def test_token_refresh_cooldown_prevents_rapid_retries(self, settings):
+        """Token refresh should enforce cooldown after failure (issue #54)."""
+        broker = KISBroker(settings)
+        broker._refresh_cooldown = 2.0  # Short cooldown for testing
+
+        # First refresh attempt fails with 403 (EGW00133)
+        mock_resp_403 = AsyncMock()
+        mock_resp_403.status = 403
+        mock_resp_403.text = AsyncMock(
+            return_value='{"error_code":"EGW00133","error_description":"접근토큰 발급 잠시 후 다시 시도하세요(1분당 1회)"}'
+        )
+        mock_resp_403.__aenter__ = AsyncMock(return_value=mock_resp_403)
+        mock_resp_403.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp_403):
+            # First attempt should fail with 403
+            with pytest.raises(ConnectionError, match="Token refresh failed"):
+                await broker._ensure_token()
+
+            # Second attempt within cooldown should fail with cooldown error
+            with pytest.raises(ConnectionError, match="Token refresh on cooldown"):
+                await broker._ensure_token()
+
+        await broker.close()
+
+    @pytest.mark.asyncio
+    async def test_token_refresh_allowed_after_cooldown(self, settings):
+        """Token refresh should be allowed after cooldown period expires."""
+        broker = KISBroker(settings)
+        broker._refresh_cooldown = 0.1  # Very short cooldown for testing
+
+        # First attempt fails
+        mock_resp_403 = AsyncMock()
+        mock_resp_403.status = 403
+        mock_resp_403.text = AsyncMock(return_value='{"error_code":"EGW00133"}')
+        mock_resp_403.__aenter__ = AsyncMock(return_value=mock_resp_403)
+        mock_resp_403.__aexit__ = AsyncMock(return_value=False)
+
+        # Second attempt succeeds
+        mock_resp_200 = AsyncMock()
+        mock_resp_200.status = 200
+        mock_resp_200.json = AsyncMock(
+            return_value={
+                "access_token": "tok_after_cooldown",
+                "expires_in": 86400,
+            }
+        )
+        mock_resp_200.__aenter__ = AsyncMock(return_value=mock_resp_200)
+        mock_resp_200.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp_403):
+            with pytest.raises(ConnectionError, match="Token refresh failed"):
+                await broker._ensure_token()
+
+        # Wait for cooldown to expire
+        await asyncio.sleep(0.15)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp_200):
+            token = await broker._ensure_token()
+            assert token == "tok_after_cooldown"
+
+        await broker.close()
+
 
 # ---------------------------------------------------------------------------
 # Network Error Handling
@@ -147,6 +211,38 @@ class TestRateLimiter:
         await broker._rate_limiter.acquire()
         await broker.close()
 
+    @pytest.mark.asyncio
+    async def test_send_order_acquires_rate_limiter_twice(self, settings):
+        """send_order must acquire rate limiter for both hash key and order call."""
+        broker = KISBroker(settings)
+        broker._access_token = "tok"
+        broker._token_expires_at = asyncio.get_event_loop().time() + 3600
+
+        # Mock hash key response
+        mock_hash_resp = AsyncMock()
+        mock_hash_resp.status = 200
+        mock_hash_resp.json = AsyncMock(return_value={"HASH": "abc123"})
+        mock_hash_resp.__aenter__ = AsyncMock(return_value=mock_hash_resp)
+        mock_hash_resp.__aexit__ = AsyncMock(return_value=False)
+
+        # Mock order response
+        mock_order_resp = AsyncMock()
+        mock_order_resp.status = 200
+        mock_order_resp.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order_resp.__aenter__ = AsyncMock(return_value=mock_order_resp)
+        mock_order_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch(
+            "aiohttp.ClientSession.post", side_effect=[mock_hash_resp, mock_order_resp]
+        ):
+            with patch.object(
+                broker._rate_limiter, "acquire", new_callable=AsyncMock
+            ) as mock_acquire:
+                await broker.send_order("005930", "BUY", 1, 50000)
+                assert mock_acquire.call_count == 2
+
+        await broker.close()
+
 
 # ---------------------------------------------------------------------------
 # Hash Key Generation
@@ -176,3 +272,27 @@ class TestHashKey:
             assert len(hash_key) > 0
 
         await broker.close()
+
+    @pytest.mark.asyncio
+    async def test_hash_key_acquires_rate_limiter(self, settings):
+        """_get_hash_key must go through the rate limiter to prevent burst."""
+        broker = KISBroker(settings)
+        broker._access_token = "tok"
+        broker._token_expires_at = asyncio.get_event_loop().time() + 3600
+
+        body = {"CANO": "12345678", "ACNT_PRDT_CD": "01"}
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"HASH": "abc123hash"})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            with patch.object(
+                broker._rate_limiter, "acquire", new_callable=AsyncMock
+            ) as mock_acquire:
+                await broker._get_hash_key(body)
+                mock_acquire.assert_called_once()
+
+        await broker.close()

tests/test_main.py

@@ -6,7 +6,43 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 
 from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected
-from src.main import trading_cycle
+from src.main import safe_float, trading_cycle
+
+
+class TestSafeFloat:
+    """Test safe_float() helper function."""
+
+    def test_converts_valid_string(self):
+        """Test conversion of valid numeric string."""
+        assert safe_float("123.45") == 123.45
+        assert safe_float("0") == 0.0
+        assert safe_float("-99.9") == -99.9
+
+    def test_handles_empty_string(self):
+        """Test empty string returns default."""
+        assert safe_float("") == 0.0
+        assert safe_float("", 99.0) == 99.0
+
+    def test_handles_none(self):
+        """Test None returns default."""
+        assert safe_float(None) == 0.0
+        assert safe_float(None, 42.0) == 42.0
+
+    def test_handles_invalid_string(self):
+        """Test invalid string returns default."""
+        assert safe_float("invalid") == 0.0
+        assert safe_float("not_a_number", 100.0) == 100.0
+        assert safe_float("12.34.56") == 0.0
+
+    def test_handles_float_input(self):
+        """Test float input passes through."""
+        assert safe_float(123.45) == 123.45
+        assert safe_float(0.0) == 0.0
+
+    def test_custom_default(self):
+        """Test custom default value."""
+        assert safe_float("", -1.0) == -1.0
+        assert safe_float(None, 999.0) == 999.0
 
 
 class TestTradingCycleTelegramIntegration:
@@ -138,6 +174,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify notification was sent
@@ -180,6 +217,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify notification was attempted
@@ -221,6 +259,7 @@ class TestTradingCycleTelegramIntegration:
                     telegram=mock_telegram,
                     market=mock_market,
                     stock_code="005930",
+                    scan_candidates={},
                 )
 
         # Verify notification was sent
@@ -269,6 +308,7 @@ class TestTradingCycleTelegramIntegration:
                     telegram=mock_telegram,
                     market=mock_market,
                     stock_code="005930",
+                    scan_candidates={},
                 )
 
         # Verify notification was attempted
@@ -309,6 +349,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify no trade notification sent
@@ -394,6 +435,26 @@ class TestOverseasBalanceParsing:
         broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
         return broker
 
+    @pytest.fixture
+    def mock_overseas_broker_with_empty_price(self) -> MagicMock:
+        """Create mock overseas broker returning empty string for price."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": ""}}  # Empty string
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "frcr_evlu_tota": "10000.00",
+                        "frcr_dncl_amt_2": "5000.00",
+                        "frcr_buy_amt_smtl": "4500.00",
+                    }
+                ]
+            }
+        )
+        return broker
+
     @pytest.fixture
     def mock_domestic_broker(self) -> MagicMock:
         """Create minimal mock domestic broker."""
@@ -487,6 +548,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
@@ -521,6 +583,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
@@ -555,7 +618,43 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
         mock_overseas_broker_with_empty.get_overseas_balance.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_overseas_price_empty_string(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_empty_price: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas price parsing with empty string (issue #49)."""
+        with patch("src.main.log_trade"):
+            # Should not raise ValueError, should default to 0.0
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_empty_price,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+                scan_candidates={},
+            )
+
+        # Verify price API was called
+        mock_overseas_broker_with_empty_price.get_overseas_price.assert_called_once()

tests/test_smart_scanner.py

@@ -0,0 +1,377 @@
+"""Tests for SmartVolatilityScanner."""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
+from src.analysis.volatility import VolatilityAnalyzer
+from src.broker.kis_api import KISBroker
+from src.config import Settings
+
+
+@pytest.fixture
+def mock_settings() -> Settings:
+    """Create test settings."""
+    return Settings(
+        KIS_APP_KEY="test",
+        KIS_APP_SECRET="test",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test",
+        RSI_OVERSOLD_THRESHOLD=30,
+        RSI_MOMENTUM_THRESHOLD=70,
+        VOL_MULTIPLIER=2.0,
+        SCANNER_TOP_N=3,
+        DB_PATH=":memory:",
+    )
+
+
+@pytest.fixture
+def mock_broker(mock_settings: Settings) -> MagicMock:
+    """Create mock broker."""
+    broker = MagicMock(spec=KISBroker)
+    broker._settings = mock_settings
+    broker.fetch_market_rankings = AsyncMock()
+    broker.get_daily_prices = AsyncMock()
+    return broker
+
+
+@pytest.fixture
+def scanner(mock_broker: MagicMock, mock_settings: Settings) -> SmartVolatilityScanner:
+    """Create smart scanner instance."""
+    analyzer = VolatilityAnalyzer()
+    return SmartVolatilityScanner(
+        broker=mock_broker,
+        volatility_analyzer=analyzer,
+        settings=mock_settings,
+    )
+
+
+class TestSmartVolatilityScanner:
+    """Test suite for SmartVolatilityScanner."""
+
+    @pytest.mark.asyncio
+    async def test_scan_finds_oversold_candidates(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scanner identifies oversold stocks with high volume."""
+        # Mock rankings
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "005930",
+                "name": "Samsung",
+                "price": 70000,
+                "volume": 5000000,
+                "change_rate": -3.5,
+                "volume_increase_rate": 250,
+            },
+        ]
+
+        # Mock daily prices - trending down (oversold)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 75000 - i * 200,
+                "high": 75500 - i * 200,
+                "low": 74500 - i * 200,
+                "close": 75000 - i * 250,  # Steady decline
+                "volume": 2000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should find at least one candidate (depending on exact RSI calculation)
+        mock_broker.fetch_market_rankings.assert_called_once()
+        mock_broker.get_daily_prices.assert_called_once_with("005930", days=20)
+
+        # If qualified, should have oversold signal
+        if candidates:
+            assert candidates[0].signal in ["oversold", "momentum"]
+            assert candidates[0].volume_ratio >= scanner.vol_multiplier
+
+    @pytest.mark.asyncio
+    async def test_scan_finds_momentum_candidates(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scanner identifies momentum stocks with high volume."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "035420",
+                "name": "NAVER",
+                "price": 250000,
+                "volume": 3000000,
+                "change_rate": 5.0,
+                "volume_increase_rate": 300,
+            },
+        ]
+
+        # Mock daily prices - trending up (momentum)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 230000 + i * 500,
+                "high": 231000 + i * 500,
+                "low": 229000 + i * 500,
+                "close": 230500 + i * 500,  # Steady rise
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        mock_broker.fetch_market_rankings.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_scan_filters_low_volume(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with low volume ratio are filtered out."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "000660",
+                "name": "SK Hynix",
+                "price": 150000,
+                "volume": 500000,
+                "change_rate": -5.0,
+                "volume_increase_rate": 50,  # Only 50% increase (< 200%)
+            },
+        ]
+
+        # Low volume
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 150000 - i * 100,
+                "high": 151000 - i * 100,
+                "low": 149000 - i * 100,
+                "close": 150000 - i * 150,  # Declining (would be oversold)
+                "volume": 1000000,  # Current 500k < 2x prev day 1M
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should be filtered out due to low volume ratio
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_scan_filters_neutral_rsi(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with neutral RSI are filtered out."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "051910",
+                "name": "LG Chem",
+                "price": 500000,
+                "volume": 3000000,
+                "change_rate": 0.5,
+                "volume_increase_rate": 300,  # High volume
+            },
+        ]
+
+        # Flat prices (neutral RSI ~50)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 500000 + (i % 2) * 100,  # Small oscillation
+                "high": 500500,
+                "low": 499500,
+                "close": 500000 + (i % 2) * 50,
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should be filtered out (RSI ~50, not < 30 or > 70)
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_scan_uses_fallback_on_api_error(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test fallback to static list when ranking API fails."""
+        mock_broker.fetch_market_rankings.side_effect = ConnectionError("API unavailable")
+
+        # Fallback stocks should still be analyzed
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 50000 - i * 50,
+                "high": 51000 - i * 50,
+                "low": 49000 - i * 50,
+                "close": 50000 - i * 75,  # Declining
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan(fallback_stocks=["005930", "000660"])
+
+        # Should not crash
+        assert isinstance(candidates, list)
+
+    @pytest.mark.asyncio
+    async def test_scan_returns_top_n_only(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scan returns at most top_n candidates."""
+        # Return many stocks
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": f"00{i}000",
+                "name": f"Stock{i}",
+                "price": 10000 * i,
+                "volume": 5000000,
+                "change_rate": -10,
+                "volume_increase_rate": 500,
+            }
+            for i in range(1, 10)
+        ]
+
+        # All oversold with high volume
+        def make_prices(code: str) -> list[dict]:
+            prices = []
+            for i in range(20):
+                prices.append({
+                    "date": f"2026020{i:02d}",
+                    "open": 10000 - i * 100,
+                    "high": 10500 - i * 100,
+                    "low": 9500 - i * 100,
+                    "close": 10000 - i * 150,
+                    "volume": 1000000,
+                })
+            return prices
+
+        mock_broker.get_daily_prices.side_effect = make_prices
+
+        candidates = await scanner.scan()
+
+        # Should respect top_n limit (3)
+        assert len(candidates) <= scanner.top_n
+
+    @pytest.mark.asyncio
+    async def test_scan_skips_insufficient_price_history(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with insufficient history are skipped."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "005930",
+                "name": "Samsung",
+                "price": 70000,
+                "volume": 5000000,
+                "change_rate": -5.0,
+                "volume_increase_rate": 300,
+            },
+        ]
+
+        # Only 5 days of data (need 15+ for RSI)
+        mock_broker.get_daily_prices.return_value = [
+            {
+                "date": f"2026020{i:02d}",
+                "open": 70000,
+                "high": 71000,
+                "low": 69000,
+                "close": 70000,
+                "volume": 2000000,
+            }
+            for i in range(5)
+        ]
+
+        candidates = await scanner.scan()
+
+        # Should skip due to insufficient data
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_get_stock_codes(
+        self, scanner: SmartVolatilityScanner
+    ) -> None:
+        """Test extraction of stock codes from candidates."""
+        candidates = [
+            ScanCandidate(
+                stock_code="005930",
+                name="Samsung",
+                price=70000,
+                volume=5000000,
+                volume_ratio=2.5,
+                rsi=28,
+                signal="oversold",
+                score=85.0,
+            ),
+            ScanCandidate(
+                stock_code="035420",
+                name="NAVER",
+                price=250000,
+                volume=3000000,
+                volume_ratio=3.0,
+                rsi=75,
+                signal="momentum",
+                score=88.0,
+            ),
+        ]
+
+        codes = scanner.get_stock_codes(candidates)
+
+        assert codes == ["005930", "035420"]
+
+
+class TestRSICalculation:
+    """Test RSI calculation in VolatilityAnalyzer."""
+
+    def test_rsi_oversold(self) -> None:
+        """Test RSI calculation for downtrending prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Steadily declining prices
+        prices = [100 - i * 0.5 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi < 50  # Should be oversold territory
+
+    def test_rsi_overbought(self) -> None:
+        """Test RSI calculation for uptrending prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Steadily rising prices
+        prices = [100 + i * 0.5 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi > 50  # Should be overbought territory
+
+    def test_rsi_neutral(self) -> None:
+        """Test RSI calculation for flat prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Flat prices with small oscillation
+        prices = [100 + (i % 2) * 0.1 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert 40 < rsi < 60  # Should be near neutral
+
+    def test_rsi_insufficient_data(self) -> None:
+        """Test RSI returns neutral when insufficient data."""
+        analyzer = VolatilityAnalyzer()
+
+        prices = [100, 101, 102]  # Only 3 prices, need 15+
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi == 50.0  # Default neutral
+
+    def test_rsi_all_gains(self) -> None:
+        """Test RSI returns 100 when all gains (no losses)."""
+        analyzer = VolatilityAnalyzer()
+
+        # Monotonic increase
+        prices = [100 + i for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi == 100.0  # Maximum RSI

tests/test_strategy_models.py

@@ -0,0 +1,366 @@
+"""Tests for strategy/playbook Pydantic models."""
+
+from __future__ import annotations
+
+from datetime import date
+
+import pytest
+from pydantic import ValidationError
+
+from src.strategy.models import (
+    CrossMarketContext,
+    DayPlaybook,
+    GlobalRule,
+    MarketOutlook,
+    PlaybookStatus,
+    ScenarioAction,
+    StockCondition,
+    StockPlaybook,
+    StockScenario,
+)
+
+
+# ---------------------------------------------------------------------------
+# StockCondition
+# ---------------------------------------------------------------------------
+
+
+class TestStockCondition:
+    def test_empty_condition(self) -> None:
+        cond = StockCondition()
+        assert not cond.has_any_condition()
+
+    def test_single_field(self) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert cond.has_any_condition()
+
+    def test_multiple_fields(self) -> None:
+        cond = StockCondition(rsi_below=25.0, volume_ratio_above=3.0)
+        assert cond.has_any_condition()
+
+    def test_all_fields(self) -> None:
+        cond = StockCondition(
+            rsi_below=30,
+            rsi_above=10,
+            volume_ratio_above=2.0,
+            volume_ratio_below=10.0,
+            price_above=1000,
+            price_below=50000,
+            price_change_pct_above=-5.0,
+            price_change_pct_below=5.0,
+        )
+        assert cond.has_any_condition()
+
+
+# ---------------------------------------------------------------------------
+# StockScenario
+# ---------------------------------------------------------------------------
+
+
+class TestStockScenario:
+    def test_valid_scenario(self) -> None:
+        s = StockScenario(
+            condition=StockCondition(rsi_below=25.0),
+            action=ScenarioAction.BUY,
+            confidence=85,
+            allocation_pct=15.0,
+            stop_loss_pct=-2.0,
+            take_profit_pct=3.0,
+            rationale="Oversold bounce expected",
+        )
+        assert s.action == ScenarioAction.BUY
+        assert s.confidence == 85
+
+    def test_confidence_too_high(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=101,
+            )
+
+    def test_confidence_too_low(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=-1,
+            )
+
+    def test_allocation_too_high(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                allocation_pct=101.0,
+            )
+
+    def test_stop_loss_must_be_negative(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                stop_loss_pct=1.0,
+            )
+
+    def test_take_profit_must_be_positive(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                take_profit_pct=-1.0,
+            )
+
+    def test_defaults(self) -> None:
+        s = StockScenario(
+            condition=StockCondition(),
+            action=ScenarioAction.HOLD,
+            confidence=50,
+        )
+        assert s.allocation_pct == 10.0
+        assert s.stop_loss_pct == -2.0
+        assert s.take_profit_pct == 3.0
+        assert s.rationale == ""
+
+
+# ---------------------------------------------------------------------------
+# StockPlaybook
+# ---------------------------------------------------------------------------
+
+
+class TestStockPlaybook:
+    def test_valid_playbook(self) -> None:
+        pb = StockPlaybook(
+            stock_code="005930",
+            stock_name="Samsung Electronics",
+            scenarios=[
+                StockScenario(
+                    condition=StockCondition(rsi_below=25.0),
+                    action=ScenarioAction.BUY,
+                    confidence=85,
+                ),
+            ],
+        )
+        assert pb.stock_code == "005930"
+        assert len(pb.scenarios) == 1
+
+    def test_empty_scenarios_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            StockPlaybook(
+                stock_code="005930",
+                scenarios=[],
+            )
+
+    def test_multiple_scenarios(self) -> None:
+        pb = StockPlaybook(
+            stock_code="AAPL",
+            scenarios=[
+                StockScenario(
+                    condition=StockCondition(rsi_below=25.0),
+                    action=ScenarioAction.BUY,
+                    confidence=85,
+                ),
+                StockScenario(
+                    condition=StockCondition(rsi_above=75.0),
+                    action=ScenarioAction.SELL,
+                    confidence=80,
+                ),
+            ],
+        )
+        assert len(pb.scenarios) == 2
+
+
+# ---------------------------------------------------------------------------
+# GlobalRule
+# ---------------------------------------------------------------------------
+
+
+class TestGlobalRule:
+    def test_valid_rule(self) -> None:
+        rule = GlobalRule(
+            condition="portfolio_pnl_pct < -2.0",
+            action=ScenarioAction.REDUCE_ALL,
+            rationale="Risk limit approaching",
+        )
+        assert rule.action == ScenarioAction.REDUCE_ALL
+
+    def test_hold_rule(self) -> None:
+        rule = GlobalRule(
+            condition="volatility_index > 30",
+            action=ScenarioAction.HOLD,
+        )
+        assert rule.rationale == ""
+
+
+# ---------------------------------------------------------------------------
+# CrossMarketContext
+# ---------------------------------------------------------------------------
+
+
+class TestCrossMarketContext:
+    def test_valid_context(self) -> None:
+        ctx = CrossMarketContext(
+            market="US",
+            date="2026-02-07",
+            total_pnl=-1.5,
+            win_rate=40.0,
+            index_change_pct=-2.3,
+            key_events=["Fed rate decision"],
+            lessons=["Avoid tech sector on rate hike days"],
+        )
+        assert ctx.market == "US"
+        assert len(ctx.key_events) == 1
+
+    def test_defaults(self) -> None:
+        ctx = CrossMarketContext(market="KR", date="2026-02-07")
+        assert ctx.total_pnl == 0.0
+        assert ctx.key_events == []
+        assert ctx.lessons == []
+
+
+# ---------------------------------------------------------------------------
+# DayPlaybook
+# ---------------------------------------------------------------------------
+
+
+def _make_scenario(rsi_below: float = 25.0) -> StockScenario:
+    return StockScenario(
+        condition=StockCondition(rsi_below=rsi_below),
+        action=ScenarioAction.BUY,
+        confidence=85,
+    )
+
+
+def _make_playbook(**kwargs) -> DayPlaybook:
+    defaults = {
+        "date": date(2026, 2, 7),
+        "market": "KR",
+        "stock_playbooks": [
+            StockPlaybook(stock_code="005930", scenarios=[_make_scenario()]),
+        ],
+    }
+    defaults.update(kwargs)
+    return DayPlaybook(**defaults)
+
+
+class TestDayPlaybook:
+    def test_valid_playbook(self) -> None:
+        pb = _make_playbook()
+        assert pb.market == "KR"
+        assert pb.date == date(2026, 2, 7)
+        assert pb.default_action == ScenarioAction.HOLD
+        assert pb.scenario_count == 1
+        assert pb.stock_count == 1
+
+    def test_generated_at_auto_set(self) -> None:
+        pb = _make_playbook()
+        assert pb.generated_at != ""
+
+    def test_explicit_generated_at(self) -> None:
+        pb = _make_playbook(generated_at="2026-02-07T08:30:00")
+        assert pb.generated_at == "2026-02-07T08:30:00"
+
+    def test_duplicate_stocks_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            DayPlaybook(
+                date=date(2026, 2, 7),
+                market="KR",
+                stock_playbooks=[
+                    StockPlaybook(stock_code="005930", scenarios=[_make_scenario()]),
+                    StockPlaybook(stock_code="005930", scenarios=[_make_scenario(30)]),
+                ],
+            )
+
+    def test_empty_stock_playbooks_allowed(self) -> None:
+        pb = DayPlaybook(
+            date=date(2026, 2, 7),
+            market="KR",
+            stock_playbooks=[],
+        )
+        assert pb.stock_count == 0
+        assert pb.scenario_count == 0
+
+    def test_get_stock_playbook_found(self) -> None:
+        pb = _make_playbook()
+        result = pb.get_stock_playbook("005930")
+        assert result is not None
+        assert result.stock_code == "005930"
+
+    def test_get_stock_playbook_not_found(self) -> None:
+        pb = _make_playbook()
+        result = pb.get_stock_playbook("AAPL")
+        assert result is None
+
+    def test_with_global_rules(self) -> None:
+        pb = _make_playbook(
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                ),
+            ],
+        )
+        assert len(pb.global_rules) == 1
+
+    def test_with_cross_market_context(self) -> None:
+        ctx = CrossMarketContext(market="US", date="2026-02-07", total_pnl=-1.5)
+        pb = _make_playbook(cross_market=ctx)
+        assert pb.cross_market is not None
+        assert pb.cross_market.market == "US"
+
+    def test_market_outlook(self) -> None:
+        pb = _make_playbook(market_outlook=MarketOutlook.BEARISH)
+        assert pb.market_outlook == MarketOutlook.BEARISH
+
+    def test_multiple_stocks_multiple_scenarios(self) -> None:
+        pb = DayPlaybook(
+            date=date(2026, 2, 7),
+            market="US",
+            stock_playbooks=[
+                StockPlaybook(
+                    stock_code="AAPL",
+                    scenarios=[_make_scenario(), _make_scenario(30)],
+                ),
+                StockPlaybook(
+                    stock_code="MSFT",
+                    scenarios=[_make_scenario()],
+                ),
+            ],
+        )
+        assert pb.stock_count == 2
+        assert pb.scenario_count == 3
+
+    def test_serialization_roundtrip(self) -> None:
+        pb = _make_playbook(
+            market_outlook=MarketOutlook.BULLISH,
+            cross_market=CrossMarketContext(market="US", date="2026-02-07"),
+        )
+        json_str = pb.model_dump_json()
+        restored = DayPlaybook.model_validate_json(json_str)
+        assert restored.market == pb.market
+        assert restored.date == pb.date
+        assert restored.scenario_count == pb.scenario_count
+        assert restored.cross_market is not None
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class TestEnums:
+    def test_scenario_action_values(self) -> None:
+        assert ScenarioAction.BUY.value == "BUY"
+        assert ScenarioAction.SELL.value == "SELL"
+        assert ScenarioAction.HOLD.value == "HOLD"
+        assert ScenarioAction.REDUCE_ALL.value == "REDUCE_ALL"
+
+    def test_market_outlook_values(self) -> None:
+        assert len(MarketOutlook) == 5
+
+    def test_playbook_status_values(self) -> None:
+        assert PlaybookStatus.READY.value == "ready"
+        assert PlaybookStatus.EXPIRED.value == "expired"

tests/test_telegram.py

@@ -39,6 +39,76 @@ class TestTelegramClientInit:
 class TestNotificationSending:
     """Test notification sending behavior."""
 
+    @pytest.mark.asyncio
+    async def test_send_message_success(self) -> None:
+        """send_message returns True on successful send."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            result = await client.send_message("Test message")
+
+            assert result is True
+            assert mock_post.call_count == 1
+
+            payload = mock_post.call_args.kwargs["json"]
+            assert payload["chat_id"] == "456"
+            assert payload["text"] == "Test message"
+            assert payload["parse_mode"] == "HTML"
+
+    @pytest.mark.asyncio
+    async def test_send_message_disabled_client(self) -> None:
+        """send_message returns False when client disabled."""
+        client = TelegramClient(enabled=False)
+
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            result = await client.send_message("Test message")
+
+            assert result is False
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_send_message_api_error(self) -> None:
+        """send_message returns False on API error."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 400
+        mock_resp.text = AsyncMock(return_value="Bad Request")
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            result = await client.send_message("Test message")
+            assert result is False
+
+    @pytest.mark.asyncio
+    async def test_send_message_with_markdown(self) -> None:
+        """send_message supports different parse modes."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True
+        )
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            result = await client.send_message("*bold*", parse_mode="Markdown")
+
+            assert result is True
+            payload = mock_post.call_args.kwargs["json"]
+            assert payload["parse_mode"] == "Markdown"
+
     @pytest.mark.asyncio
     async def test_no_send_when_disabled(self) -> None:
         """Notifications not sent when client disabled."""

tests/test_telegram_commands.py

@@ -0,0 +1,777 @@
+"""Tests for Telegram command handler."""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from src.notifications.telegram_client import TelegramClient, TelegramCommandHandler
+
+
+class TestCommandHandlerInit:
+    """Test command handler initialization."""
+
+    def test_init_with_client(self) -> None:
+        """Handler initializes with TelegramClient."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        assert handler._client is client
+        assert handler._polling_interval == 1.0
+        assert handler._commands == {}
+        assert handler._running is False
+
+    def test_custom_polling_interval(self) -> None:
+        """Handler accepts custom polling interval."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client, polling_interval=2.5)
+
+        assert handler._polling_interval == 2.5
+
+
+class TestCommandRegistration:
+    """Test command registration."""
+
+    @pytest.mark.asyncio
+    async def test_register_command(self) -> None:
+        """Commands can be registered."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        async def test_handler() -> None:
+            pass
+
+        handler.register_command("test", test_handler)
+
+        assert "test" in handler._commands
+        assert handler._commands["test"] is test_handler
+
+    @pytest.mark.asyncio
+    async def test_register_multiple_commands(self) -> None:
+        """Multiple commands can be registered."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        async def handler1() -> None:
+            pass
+
+        async def handler2() -> None:
+            pass
+
+        handler.register_command("start", handler1)
+        handler.register_command("help", handler2)
+
+        assert len(handler._commands) == 2
+        assert handler._commands["start"] is handler1
+        assert handler._commands["help"] is handler2
+
+
+class TestPollingLifecycle:
+    """Test polling start/stop."""
+
+    @pytest.mark.asyncio
+    async def test_start_polling(self) -> None:
+        """Polling can be started."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        with patch.object(handler, "_poll_loop", new_callable=AsyncMock):
+            await handler.start_polling()
+
+            assert handler._running is True
+            assert handler._polling_task is not None
+
+        await handler.stop_polling()
+
+    @pytest.mark.asyncio
+    async def test_start_polling_disabled_client(self) -> None:
+        """Polling not started when client disabled."""
+        client = TelegramClient(enabled=False)
+        handler = TelegramCommandHandler(client)
+
+        await handler.start_polling()
+
+        assert handler._running is False
+        assert handler._polling_task is None
+
+    @pytest.mark.asyncio
+    async def test_stop_polling(self) -> None:
+        """Polling can be stopped."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        with patch.object(handler, "_poll_loop", new_callable=AsyncMock):
+            await handler.start_polling()
+            await handler.stop_polling()
+
+            assert handler._running is False
+
+    @pytest.mark.asyncio
+    async def test_double_start_ignored(self) -> None:
+        """Starting already running handler is ignored."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        with patch.object(handler, "_poll_loop", new_callable=AsyncMock):
+            await handler.start_polling()
+            task1 = handler._polling_task
+
+            await handler.start_polling()  # Second start
+            task2 = handler._polling_task
+
+            # Should be the same task
+            assert task1 is task2
+
+        await handler.stop_polling()
+
+
+class TestUpdateHandling:
+    """Test update parsing and handling."""
+
+    @pytest.mark.asyncio
+    async def test_handle_valid_command(self) -> None:
+        """Valid commands are executed."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        executed = False
+
+        async def test_command() -> None:
+            nonlocal executed
+            executed = True
+
+        handler.register_command("test", test_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 456},
+                "text": "/test",
+            },
+        }
+
+        await handler._handle_update(update)
+        assert executed is True
+
+    @pytest.mark.asyncio
+    async def test_handle_unknown_command(self) -> None:
+        """Unknown commands send help message."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/unknown",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Should send error message
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Unknown command" in payload["text"]
+            assert "/unknown" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_ignore_unauthorized_chat(self) -> None:
+        """Commands from unauthorized chats are ignored."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        executed = False
+
+        async def test_command() -> None:
+            nonlocal executed
+            executed = True
+
+        handler.register_command("test", test_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 999},  # Wrong chat_id
+                "text": "/test",
+            },
+        }
+
+        await handler._handle_update(update)
+        assert executed is False
+
+    @pytest.mark.asyncio
+    async def test_ignore_non_command_text(self) -> None:
+        """Non-command text is ignored."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        executed = False
+
+        async def test_command() -> None:
+            nonlocal executed
+            executed = True
+
+        handler.register_command("test", test_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 456},
+                "text": "Hello, not a command",
+            },
+        }
+
+        await handler._handle_update(update)
+        assert executed is False
+
+    @pytest.mark.asyncio
+    async def test_handle_command_with_botname(self) -> None:
+        """Commands with @botname suffix are handled correctly."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        executed = False
+
+        async def test_command() -> None:
+            nonlocal executed
+            executed = True
+
+        handler.register_command("start", test_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 456},
+                "text": "/start@mybot",
+            },
+        }
+
+        await handler._handle_update(update)
+        assert executed is True
+
+    @pytest.mark.asyncio
+    async def test_handle_update_error_isolation(self) -> None:
+        """Errors in handlers don't crash the system."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        async def failing_command() -> None:
+            raise ValueError("Test error")
+
+        handler.register_command("fail", failing_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 456},
+                "text": "/fail",
+            },
+        }
+
+        # Should not raise exception
+        await handler._handle_update(update)
+
+
+class TestTradingControlCommands:
+    """Test trading control commands."""
+
+    @pytest.mark.asyncio
+    async def test_stop_command_pauses_trading(self) -> None:
+        """Stop command clears pause event."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        # Create mock pause event
+        import asyncio
+
+        pause_event = asyncio.Event()
+        pause_event.set()  # Initially active
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_stop() -> None:
+            """Mock /stop handler."""
+            if not pause_event.is_set():
+                await client.send_message("⏸️ Trading is already paused")
+                return
+
+            pause_event.clear()
+            await client.send_message(
+                "<b>⏸️ Trading Paused</b>\n\n"
+                "All trading operations have been suspended.\n"
+                "Use /resume to restart trading."
+            )
+
+        handler.register_command("stop", mock_stop)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/stop",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify pause event was cleared
+            assert not pause_event.is_set()
+
+            # Verify message was sent
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Trading Paused" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_resume_command_resumes_trading(self) -> None:
+        """Resume command sets pause event."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        # Create mock pause event (initially paused)
+        import asyncio
+
+        pause_event = asyncio.Event()
+        pause_event.clear()  # Initially paused
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_resume() -> None:
+            """Mock /resume handler."""
+            if pause_event.is_set():
+                await client.send_message("▶️ Trading is already active")
+                return
+
+            pause_event.set()
+            await client.send_message(
+                "<b>▶️ Trading Resumed</b>\n\n"
+                "Trading operations have been restarted."
+            )
+
+        handler.register_command("resume", mock_resume)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/resume",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify pause event was set
+            assert pause_event.is_set()
+
+            # Verify message was sent
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Trading Resumed" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_stop_when_already_paused(self) -> None:
+        """Stop command when already paused sends appropriate message."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        # Create mock pause event (already paused)
+        import asyncio
+
+        pause_event = asyncio.Event()
+        pause_event.clear()
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_stop() -> None:
+            """Mock /stop handler."""
+            if not pause_event.is_set():
+                await client.send_message("⏸️ Trading is already paused")
+                return
+
+            pause_event.clear()
+
+        handler.register_command("stop", mock_stop)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/stop",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            payload = mock_post.call_args.kwargs["json"]
+            assert "already paused" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_resume_when_already_active(self) -> None:
+        """Resume command when already active sends appropriate message."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        # Create mock pause event (already active)
+        import asyncio
+
+        pause_event = asyncio.Event()
+        pause_event.set()
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_resume() -> None:
+            """Mock /resume handler."""
+            if pause_event.is_set():
+                await client.send_message("▶️ Trading is already active")
+                return
+
+            pause_event.set()
+
+        handler.register_command("resume", mock_resume)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/resume",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            payload = mock_post.call_args.kwargs["json"]
+            assert "already active" in payload["text"]
+
+
+class TestStatusCommands:
+    """Test status query commands."""
+
+    @pytest.mark.asyncio
+    async def test_status_command_shows_trading_info(self) -> None:
+        """Status command displays mode, markets, and P&L."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_status() -> None:
+            """Mock /status handler."""
+            message = (
+                "<b>📊 Trading Status</b>\n\n"
+                "<b>Mode:</b> PAPER\n"
+                "<b>Markets:</b> Korea, United States\n"
+                "<b>Trading:</b> Active\n\n"
+                "<b>Current P&L:</b> +2.50%\n"
+                "<b>Circuit Breaker:</b> -3.0%"
+            )
+            await client.send_message(message)
+
+        handler.register_command("status", mock_status)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/status",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Trading Status" in payload["text"]
+            assert "PAPER" in payload["text"]
+            assert "P&L" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_status_command_error_handling(self) -> None:
+        """Status command handles errors gracefully."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_status_error() -> None:
+            """Mock /status handler with error."""
+            await client.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve trading status."
+            )
+
+        handler.register_command("status", mock_status_error)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/status",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Should send error message
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Error" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_positions_command_shows_holdings(self) -> None:
+        """Positions command displays account summary."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_positions() -> None:
+            """Mock /positions handler."""
+            message = (
+                "<b>💼 Account Summary</b>\n\n"
+                "<b>Total Evaluation:</b> ₩10,500,000\n"
+                "<b>Available Cash:</b> ₩5,000,000\n"
+                "<b>Purchase Total:</b> ₩10,000,000\n"
+                "<b>P&L:</b> +5.00%\n\n"
+                "<i>Note: Individual position details require API enhancement</i>"
+            )
+            await client.send_message(message)
+
+        handler.register_command("positions", mock_positions)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/positions",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Account Summary" in payload["text"]
+            assert "Total Evaluation" in payload["text"]
+            assert "P&L" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_positions_command_empty_holdings(self) -> None:
+        """Positions command handles empty portfolio."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_positions_empty() -> None:
+            """Mock /positions handler with no positions."""
+            message = (
+                "<b>💼 Account Summary</b>\n\n"
+                "No balance information available."
+            )
+            await client.send_message(message)
+
+        handler.register_command("positions", mock_positions_empty)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/positions",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            payload = mock_post.call_args.kwargs["json"]
+            assert "No balance information available" in payload["text"]
+
+    @pytest.mark.asyncio
+    async def test_positions_command_error_handling(self) -> None:
+        """Positions command handles errors gracefully."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_positions_error() -> None:
+            """Mock /positions handler with error."""
+            await client.send_message(
+                "<b>⚠️ Error</b>\n\nFailed to retrieve positions."
+            )
+
+        handler.register_command("positions", mock_positions_error)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/positions",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Should send error message
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Error" in payload["text"]
+
+
+class TestBasicCommands:
+    """Test basic command implementations."""
+
+    @pytest.mark.asyncio
+    async def test_help_command_content(self) -> None:
+        """Help command lists all available commands."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        async def mock_help() -> None:
+            """Mock /help handler."""
+            message = (
+                "<b>📖 Available Commands</b>\n\n"
+                "/help - Show available commands\n"
+                "/status - Trading status (mode, markets, P&L)\n"
+                "/positions - Current holdings\n"
+                "/stop - Pause trading\n"
+                "/resume - Resume trading"
+            )
+            await client.send_message(message)
+
+        handler.register_command("help", mock_help)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
+            update = {
+                "update_id": 1,
+                "message": {
+                    "chat": {"id": 456},
+                    "text": "/help",
+                },
+            }
+
+            await handler._handle_update(update)
+
+            # Verify message was sent
+            assert mock_post.call_count == 1
+            payload = mock_post.call_args.kwargs["json"]
+            assert "Available Commands" in payload["text"]
+            assert "/help" in payload["text"]
+            assert "/status" in payload["text"]
+            assert "/positions" in payload["text"]
+            assert "/stop" in payload["text"]
+            assert "/resume" in payload["text"]
+
+
+class TestGetUpdates:
+    """Test getUpdates API interaction."""
+
+    @pytest.mark.asyncio
+    async def test_get_updates_success(self) -> None:
+        """getUpdates fetches and parses updates."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(
+            return_value={
+                "ok": True,
+                "result": [
+                    {"update_id": 1, "message": {"text": "/test"}},
+                    {"update_id": 2, "message": {"text": "/help"}},
+                ],
+            }
+        )
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            updates = await handler._get_updates()
+
+            assert len(updates) == 2
+            assert updates[0]["update_id"] == 1
+            assert updates[1]["update_id"] == 2
+            assert handler._last_update_id == 2
+
+    @pytest.mark.asyncio
+    async def test_get_updates_api_error(self) -> None:
+        """getUpdates handles API errors gracefully."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 400
+        mock_resp.text = AsyncMock(return_value="Bad Request")
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            updates = await handler._get_updates()
+
+            assert updates == []
+
+    @pytest.mark.asyncio
+    async def test_get_updates_empty_result(self) -> None:
+        """getUpdates handles empty results."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"ok": True, "result": []})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", return_value=mock_resp):
+            updates = await handler._get_updates()
+
+            assert updates == []

tests/test_volatility.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import sqlite3
 from typing import Any
 from unittest.mock import AsyncMock
@@ -338,6 +339,28 @@ class TestMarketScanner:
         assert metrics.stock_code == "AAPL"
         assert metrics.current_price == 150.50
 
+    @pytest.mark.asyncio
+    async def test_scan_stock_overseas_empty_price(
+        self,
+        scanner: MarketScanner,
+        mock_overseas_broker: OverseasBroker,
+        context_store: ContextStore,
+    ) -> None:
+        """Test scanning overseas stock with empty price string (issue #49)."""
+        mock_overseas_broker.get_overseas_price.return_value = {
+            "output": {
+                "last": "",  # Empty string
+                "tvol": "",  # Empty string
+            }
+        }
+
+        market = MARKETS["US_NASDAQ"]
+        metrics = await scanner.scan_stock("AAPL", market)
+
+        assert metrics is not None
+        assert metrics.stock_code == "AAPL"
+        assert metrics.current_price == 0.0  # Should default to 0.0
+
     @pytest.mark.asyncio
     async def test_scan_stock_error_handling(
         self,
@@ -509,3 +532,45 @@ class TestMarketScanner:
         new_additions = [code for code in updated if code not in current_watchlist]
         assert len(new_additions) <= 1
         assert len(updated) == len(current_watchlist)
+
+    @pytest.mark.asyncio
+    async def test_scan_market_respects_concurrency_limit(
+        self,
+        mock_broker: KISBroker,
+        mock_overseas_broker: OverseasBroker,
+        volatility_analyzer: VolatilityAnalyzer,
+        context_store: ContextStore,
+    ) -> None:
+        """scan_market should limit concurrent scans to max_concurrent_scans."""
+        max_concurrent = 2
+        scanner = MarketScanner(
+            broker=mock_broker,
+            overseas_broker=mock_overseas_broker,
+            volatility_analyzer=volatility_analyzer,
+            context_store=context_store,
+            top_n=5,
+            max_concurrent_scans=max_concurrent,
+        )
+
+        # Track peak concurrency
+        active_count = 0
+        peak_count = 0
+
+        original_scan = scanner.scan_stock
+
+        async def tracking_scan(code: str, market: Any) -> VolatilityMetrics:
+            nonlocal active_count, peak_count
+            active_count += 1
+            peak_count = max(peak_count, active_count)
+            await asyncio.sleep(0.05)  # Simulate API call duration
+            active_count -= 1
+            return VolatilityMetrics(code, 50000, 500, 1.0, 1.0, 1.0, 1.0, 10.0, 50.0)
+
+        scanner.scan_stock = tracking_scan  # type: ignore[method-assign]
+
+        market = MARKETS["KR"]
+        stock_codes = ["001", "002", "003", "004", "005", "006"]
+
+        await scanner.scan_market(market, stock_codes)
+
+        assert peak_count <= max_concurrent