fix: ranking API 필수 파라미터 KEYB 추가 및 GUBN 값 수정 (#258)

KIS 공식 문서(20260221) 기준 KEYB(NEXT KEY BUFF)는 Required=Y이나
누락되어 있어 항상 rt_cd=2 오류 발생, fallback 경로로만 실행됨.

- fluctuation/volume 양쪽 params에 KEYB: '' 추가
- GUBN 주석 수정: 0=하락율, 1=상승율 (문서 기준)
- GUBN 값 0→1 수정: 상승율 기준으로 변동성 급등 종목 스캔

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

docs/requirements-log.md

@@ -322,3 +322,36 @@ Order result: 모의투자 매수주문이 완료 되었습니다.  ✓
    - `TestHandleDomesticPendingOrders` (4), `TestDomesticLimitOrderPrice` (2)
 
 **이슈/PR:** #232, PR #233
+
+---
+
+## 2026-02-24
+
+### 해외잔고 ghost position 수정 — '모의투자 잔고내역이 없습니다' 반복 방지 (#235)
+
+**배경:**
+- 모의투자 실행 시 MLECW, KNRX, NBY, SNSE 등 만료/정지된 종목에 대해
+  `모의투자 잔고내역이 없습니다` 오류가 매 사이클 반복됨
+
+**근본 원인:**
+1. `ovrs_cblc_qty` (해외잔고수량, 총 보유) vs `ord_psbl_qty` (주문가능수량, 실제 매도 가능)
+   - 기존 코드: `ovrs_cblc_qty` 우선 사용 → 만료 Warrant가 `ovrs_cblc_qty=289456`이지만 실제 `ord_psbl_qty=0`
+   - startup sync / build_overseas_symbol_universe가 이 종목들을 포지션으로 기록
+2. SELL 실패 시 DB 포지션이 닫히지 않아 다음 사이클에서도 재시도 (무한 반복)
+
+**구현 내용:**
+
+1. `src/main.py` — `_extract_held_codes_from_balance`, `_extract_held_qty_from_balance`
+   - 해외 잔고 필드 우선순위 변경: `ord_psbl_qty` → `ovrs_cblc_qty` → `hldg_qty` (fallback 유지)
+   - KIS 공식 문서(VTTS3012R) 기준: `ord_psbl_qty`가 실제 매도 가능 수량
+
+2. `src/main.py` — `trading_cycle` ghost-close 처리
+   - 해외 SELL이 `잔고내역이 없습니다`로 실패 시 DB 포지션을 `[ghost-close]` SELL로 종료
+   - exchange code 불일치 등 예외 상황에서 무한 반복 방지
+
+3. 테스트 7개 추가:
+   - `TestExtractHeldQtyFromBalance` 3개: ord_psbl_qty 우선, 0이면 0 반환, fallback
+   - `TestExtractHeldCodesFromBalance` 2개: ord_psbl_qty=0인 종목 제외, fallback
+   - `TestOverseasGhostPositionClose` 2개: ghost-close 로그 확인, 일반 오류 무시
+
+**이슈/PR:** #235, PR #236

scripts/run_overnight.sh

@@ -23,7 +23,7 @@ if [ -z "${APP_CMD:-}" ]; then
 
     dashboard_port="${DASHBOARD_PORT:-8080}"
 
-    APP_CMD="DASHBOARD_PORT=$dashboard_port $PYTHON_BIN -m src.main --mode=paper --dashboard"
+    APP_CMD="DASHBOARD_PORT=$dashboard_port $PYTHON_BIN -m src.main --mode=live --dashboard"
 fi
 
 mkdir -p "$LOG_DIR"

src/brain/gemini_client.py

@@ -346,8 +346,10 @@ class GeminiClient:
         # Validate required fields
         if not all(k in data for k in ("action", "confidence", "rationale")):
             logger.warning("Missing fields in Gemini response — defaulting to HOLD")
+            # Preserve raw text in rationale so prompt_override callers (e.g. pre_market_planner)
+            # can extract their own JSON format from decision.rationale (#245)
             return TradeDecision(
-                action="HOLD", confidence=0, rationale="Missing required fields"
+                action="HOLD", confidence=0, rationale=raw
             )
 
         action = str(data["action"]).upper()
@@ -439,6 +441,18 @@ class GeminiClient:
                 action="HOLD", confidence=0, rationale=f"API error: {exc}", token_count=token_count
             )
 
+        # prompt_override callers (e.g. pre_market_planner) expect raw text back,
+        # not a parsed TradeDecision. Skip parse_response to avoid spurious
+        # "Missing fields" warnings and return the raw response directly. (#247)
+        if "prompt_override" in market_data:
+            logger.info(
+                "Gemini raw response received (prompt_override, tokens=%d)", token_count
+            )
+            # Not a trade decision — don't inflate _total_decisions metrics
+            return TradeDecision(
+                action="HOLD", confidence=0, rationale=raw, token_count=token_count
+            )
+
         decision = self.parse_response(raw)
         self._total_decisions += 1
 

src/brain/prompt_optimizer.py

@@ -179,8 +179,8 @@ class PromptOptimizer:
             # Minimal instructions
             prompt = (
                 f"{market_name} trader. Analyze:\n{data_str}\n\n"
-                'Return JSON: {"act":"BUY"|"SELL"|"HOLD","conf":<0-100>,"reason":"<text>"}\n'
+                'Return JSON: {"action":"BUY"|"SELL"|"HOLD","confidence":<0-100>,"rationale":"<text>"}\n'
-                "Rules: act=BUY/SELL/HOLD, conf=0-100, reason=concise. No markdown."
+                "Rules: action=BUY/SELL/HOLD, confidence=0-100, rationale=concise. No markdown."
             )
         else:
             # Data only (for cached contexts where instructions are known)

src/broker/kis_api.py

@@ -430,7 +430,7 @@ class KISBroker:
                 "fid_cond_mrkt_div_code": "J",
                 "fid_cond_scr_div_code": "20170",
                 "fid_input_iscd": "0000",
-                "fid_rank_sort_cls_code": "0000",
+                "fid_rank_sort_cls_code": "0",
                 "fid_input_cnt_1": str(limit),
                 "fid_prc_cls_code": "0",
                 "fid_input_price_1": "0",
@@ -466,7 +466,7 @@ class KISBroker:
             rankings = []
             for item in data.get("output", [])[:limit]:
                 rankings.append({
-                    "stock_code": item.get("mksc_shrn_iscd", ""),
+                    "stock_code": item.get("stck_shrn_iscd") or 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")),

src/broker/overseas.py

@@ -121,6 +121,7 @@ class OverseasBroker:
             tr_id = self._broker._settings.OVERSEAS_RANKING_VOLUME_TR_ID
             path = self._broker._settings.OVERSEAS_RANKING_VOLUME_PATH
             params: dict[str, str] = {
+                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                 "AUTH": "",
                 "EXCD": ranking_excd,
                 "MIXN": "0",
@@ -130,10 +131,11 @@ class OverseasBroker:
             tr_id = self._broker._settings.OVERSEAS_RANKING_FLUCT_TR_ID
             path = self._broker._settings.OVERSEAS_RANKING_FLUCT_PATH
             params = {
+                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                 "AUTH": "",
                 "EXCD": ranking_excd,
                 "NDAY": "0",
-                "GUBN": "1",
+                "GUBN": "1",  # 0=하락율, 1=상승율 — 변동성 스캐너는 급등 종목 우선
                 "VOL_RANG": "0",
             }
 

src/dashboard/app.py

@@ -13,10 +13,11 @@ from fastapi import FastAPI, HTTPException, Query
 from fastapi.responses import FileResponse
 
 
-def create_dashboard_app(db_path: str) -> FastAPI:
+def create_dashboard_app(db_path: str, mode: str = "paper") -> FastAPI:
     """Create dashboard FastAPI app bound to a SQLite database path."""
     app = FastAPI(title="The Ouroboros Dashboard", version="1.0.0")
     app.state.db_path = db_path
+    app.state.mode = mode
 
     @app.get("/")
     def index() -> FileResponse:
@@ -111,6 +112,7 @@ def create_dashboard_app(db_path: str) -> FastAPI:
 
             return {
                 "date": today,
+                "mode": mode,
                 "markets": market_status,
                 "totals": {
                     "trade_count": total_trades,

src/dashboard/static/index.html

@@ -43,6 +43,19 @@
         font-size: 12px; transition: border-color 0.2s;
       }
       .refresh-btn:hover { border-color: var(--accent); color: var(--accent); }
+      .mode-badge {
+        padding: 3px 10px; border-radius: 5px; font-size: 12px; font-weight: 700;
+        letter-spacing: 0.5px;
+      }
+      .mode-badge.live {
+        background: rgba(224, 85, 85, 0.15); color: var(--red);
+        border: 1px solid rgba(224, 85, 85, 0.4);
+        animation: pulse-warn 2s ease-in-out infinite;
+      }
+      .mode-badge.paper {
+        background: rgba(232, 160, 64, 0.15); color: var(--warn);
+        border: 1px solid rgba(232, 160, 64, 0.4);
+      }
 
       /* CB Gauge */
       .cb-gauge-wrap {
@@ -225,6 +238,7 @@
       <header>
         <h1>&#x1F40D; The Ouroboros</h1>
         <div class="header-right">
+          <span class="mode-badge" id="mode-badge">--</span>
           <div class="cb-gauge-wrap" id="cb-gauge" title="Circuit Breaker">
             <span class="cb-dot unknown" id="cb-dot"></span>
             <span id="cb-label">CB --</span>
@@ -512,9 +526,22 @@
           }
           document.getElementById('card-pnl-sub').textContent = `결정 ${t.decision_count ?? 0}건`;
           renderCbGauge(d.circuit_breaker);
+          renderModeBadge(d.mode);
         } catch {}
       }
 
+      function renderModeBadge(mode) {
+        const el = document.getElementById('mode-badge');
+        if (!el) return;
+        if (mode === 'live') {
+          el.textContent = '🔴 실전투자';
+          el.className = 'mode-badge live';
+        } else {
+          el.textContent = '🟡 모의투자';
+          el.className = 'mode-badge paper';
+        }
+      }
+
       async function fetchPerformance() {
         try {
           const r = await fetch('/api/performance?market=all');

src/main.py

@@ -182,6 +182,9 @@ async def sync_positions_from_broker(
             qty = _extract_held_qty_from_balance(
                 balance_data, stock_code, is_domestic=market.is_domestic
             )
+            avg_price = _extract_avg_price_from_balance(
+                balance_data, stock_code, is_domestic=market.is_domestic
+            )
             log_trade(
                 conn=db_conn,
                 stock_code=stock_code,
@@ -189,7 +192,7 @@ async def sync_positions_from_broker(
                 confidence=0,
                 rationale="[startup-sync] Position detected from broker at startup",
                 quantity=qty,
-                price=0.0,
+                price=avg_price,
                 market=log_market,
                 exchange_code=market.exchange_code,
                 mode=settings.MODE,
@@ -257,7 +260,15 @@ def _extract_held_codes_from_balance(
         if is_domestic:
             qty = int(holding.get("ord_psbl_qty") or holding.get("hldg_qty") or 0)
         else:
-            qty = int(holding.get("ovrs_cblc_qty") or holding.get("hldg_qty") or 0)
+            # ord_psbl_qty (주문가능수량) is the actual sellable quantity.
+            # ovrs_cblc_qty (해외잔고수량) includes unsettled/expired holdings
+            # that cannot actually be sold (e.g. expired warrants).
+            qty = int(
+                holding.get("ord_psbl_qty")
+                or holding.get("ovrs_cblc_qty")
+                or holding.get("hldg_qty")
+                or 0
+            )
         if qty > 0:
             codes.append(code)
     return codes
@@ -280,10 +291,12 @@ def _extract_held_qty_from_balance(
         ord_psbl_qty  — 주문가능수량 (preferred: excludes unsettled)
         hldg_qty      — 보유수량 (fallback)
 
-    Overseas fields (output1):
+    Overseas fields (VTTS3012R / TTTS3012R output1):
         ovrs_pdno     — 종목코드
-        ovrs_cblc_qty — 해외잔고수량 (preferred)
+        ord_psbl_qty  — 주문가능수량 (preferred: actual sellable qty)
-        hldg_qty      — 보유수량 (fallback)
+        ovrs_cblc_qty — 해외잔고수량 (fallback: total holding, may include
+                        unsettled or expired positions with ord_psbl_qty=0)
+        hldg_qty      — 보유수량 (last-resort fallback)
     """
     output1 = balance_data.get("output1", [])
     if isinstance(output1, dict):
@@ -301,11 +314,47 @@ def _extract_held_qty_from_balance(
         if is_domestic:
             qty = int(holding.get("ord_psbl_qty") or holding.get("hldg_qty") or 0)
         else:
-            qty = int(holding.get("ovrs_cblc_qty") or holding.get("hldg_qty") or 0)
+            qty = int(
+                holding.get("ord_psbl_qty")
+                or holding.get("ovrs_cblc_qty")
+                or holding.get("hldg_qty")
+                or 0
+            )
         return qty
     return 0
 
 
+def _extract_avg_price_from_balance(
+    balance_data: dict[str, Any],
+    stock_code: str,
+    *,
+    is_domestic: bool,
+) -> float:
+    """Extract the broker-reported average purchase price for a stock.
+
+    Uses ``pchs_avg_pric`` (매입평균가격) from the balance response (output1).
+    Returns 0.0 when absent so callers can use ``if price > 0`` as sentinel.
+
+    Domestic fields (VTTC8434R output1):  pdno, pchs_avg_pric
+    Overseas fields (VTTS3012R output1):  ovrs_pdno, pchs_avg_pric
+    """
+    output1 = balance_data.get("output1", [])
+    if isinstance(output1, dict):
+        output1 = [output1]
+    if not isinstance(output1, list):
+        return 0.0
+
+    for holding in output1:
+        if not isinstance(holding, dict):
+            continue
+        code_key = "pdno" if is_domestic else "ovrs_pdno"
+        held_code = str(holding.get(code_key, "")).strip().upper()
+        if held_code != stock_code.strip().upper():
+            continue
+        return safe_float(holding.get("pchs_avg_pric"), 0.0)
+    return 0.0
+
+
 def _determine_order_quantity(
     *,
     action: str,
@@ -681,7 +730,7 @@ async def trading_cycle(
         open_position = get_open_position(db_conn, stock_code, market.code)
         if open_position:
             entry_price = safe_float(open_position.get("price"), 0.0)
-            if entry_price > 0:
+            if entry_price > 0 and current_price > 0:
                 loss_pct = (current_price - entry_price) / entry_price * 100
                 stop_loss_threshold = -2.0
                 take_profit_threshold = 3.0
@@ -876,10 +925,13 @@ async def trading_cycle(
             # - SELL: -0.2% below last price — ensures fill even when price dips slightly
             #   (placing at exact last price risks no-fill if the bid is just below).
             overseas_price: float
+            # KIS requires at most 2 decimal places for prices >= $1 (≥1달러 소수점 2자리 제한).
+            # Penny stocks (< $1) keep 4 decimal places to preserve price precision.
+            _price_decimals = 2 if current_price >= 1.0 else 4
             if decision.action == "BUY":
-                overseas_price = round(current_price * 1.002, 4)
+                overseas_price = round(current_price * 1.002, _price_decimals)
             else:
-                overseas_price = round(current_price * 0.998, 4)
+                overseas_price = round(current_price * 0.998, _price_decimals)
             result = await overseas_broker.send_overseas_order(
                 exchange_code=market.exchange_code,
                 stock_code=stock_code,
@@ -908,6 +960,33 @@ async def trading_cycle(
                         stock_code,
                         _BUY_COOLDOWN_SECONDS,
                     )
+                # Close ghost position when broker has no matching balance.
+                # This prevents infinite SELL retry cycles for positions that
+                # exist in the DB (from startup sync) but are no longer
+                # sellable at the broker (expired warrants, delisted stocks, etc.)
+                if decision.action == "SELL" and "잔고내역이 없습니다" in msg1:
+                    logger.warning(
+                        "Ghost position detected for %s (%s): broker reports no balance."
+                        " Closing DB position to prevent infinite retry.",
+                        stock_code,
+                        market.exchange_code,
+                    )
+                    log_trade(
+                        conn=db_conn,
+                        stock_code=stock_code,
+                        action="SELL",
+                        confidence=0,
+                        rationale=(
+                            "[ghost-close] Broker reported no balance;"
+                            " position closed without fill"
+                        ),
+                        quantity=0,
+                        price=0.0,
+                        pnl=0.0,
+                        market=market.code,
+                        exchange_code=market.exchange_code,
+                        mode=settings.MODE if settings else "paper",
+                    )
         logger.info("Order result: %s", result.get("msg1", "OK"))
 
         # 5.5. Notify trade execution (only on success)
@@ -2003,7 +2082,7 @@ def _start_dashboard_server(settings: Settings) -> threading.Thread | None:
             import uvicorn
             from src.dashboard import create_dashboard_app
 
-            app = create_dashboard_app(settings.DB_PATH)
+            app = create_dashboard_app(settings.DB_PATH, mode=settings.MODE)
             uvicorn.run(
                 app,
                 host=settings.DASHBOARD_HOST,

src/strategies/v20260220_210124_evolved.py

@@ -1,114 +0,0 @@
-"""Auto-generated strategy: v20260220_210124
-
-Generated at: 2026-02-20T21:01:24.706847+00:00
-Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
-"""
-
-from __future__ import annotations
-from typing import Any
-from src.strategies.base import BaseStrategy
-
-
-class Strategy_v20260220_210124(BaseStrategy):
-    """Strategy: v20260220_210124"""
-
-    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
-        import datetime
-
-        # --- Strategy Constants ---
-        # Minimum price for a stock to be considered for trading (avoids penny stocks)
-        MIN_PRICE = 5.0
-
-        # Momentum signal thresholds (stricter than previous failures)
-        MOMENTUM_PRICE_CHANGE_THRESHOLD = 7.0  # % price change
-        MOMENTUM_VOLUME_RATIO_THRESHOLD = 4.0  # X times average volume
-
-        # Oversold signal thresholds (more conservative)
-        OVERSOLD_RSI_THRESHOLD = 25.0  # RSI value (lower means more oversold)
-
-        # Confidence levels
-        CONFIDENCE_HOLD = 30
-        CONFIDENCE_BUY_OVERSOLD = 65
-        CONFIDENCE_BUY_MOMENTUM = 85
-        CONFIDENCE_BUY_STRONG_MOMENTUM = 90  # For higher-priced stocks with strong momentum
-
-        # Market hours in UTC (9:30 AM ET to 4:00 PM ET)
-        MARKET_OPEN_UTC = datetime.time(14, 30)
-        MARKET_CLOSE_UTC = datetime.time(21, 0)
-
-        # Volatile periods within market hours (UTC) to avoid
-        # First hour after open (14:30 UTC - 15:30 UTC)
-        VOLATILE_OPEN_END_UTC = datetime.time(15, 30)
-        # Last 30 minutes before close (20:30 UTC - 21:00 UTC)
-        VOLATILE_CLOSE_START_UTC = datetime.time(20, 30)
-
-        current_price = market_data.get('current_price')
-        price_change_pct = market_data.get('price_change_pct')
-        volume_ratio = market_data.get('volume_ratio')  # Assumed pre-computed indicator
-        rsi = market_data.get('rsi')                    # Assumed pre-computed indicator
-        timestamp_str = market_data.get('timestamp')
-
-        action = "HOLD"
-        confidence = CONFIDENCE_HOLD
-        rationale = "Initial HOLD: No clear signal or conditions not met."
-
-        # --- 1. Basic Data Validation ---
-        if current_price is None or price_change_pct is None:
-            return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
-                    "rationale": "Insufficient core data (price or price change) to evaluate."}
-
-        # --- 2. Price Filter: Avoid low-priced/penny stocks ---
-        if current_price < MIN_PRICE:
-            return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
-                    "rationale": f"Avoiding low-priced stock (${current_price:.2f} < ${MIN_PRICE:.2f})."}
-
-        # --- 3. Time Filter: Only trade during core market hours ---
-        if timestamp_str:
-            try:
-                dt_object = datetime.datetime.fromisoformat(timestamp_str)
-                current_time_utc = dt_object.time()
-
-                if not (MARKET_OPEN_UTC <= current_time_utc < MARKET_CLOSE_UTC):
-                    return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
-                            "rationale": f"Avoiding trade outside core market hours ({current_time_utc} UTC)."}
-
-                if (MARKET_OPEN_UTC <= current_time_utc < VOLATILE_OPEN_END_UTC) or \
-                   (VOLATILE_CLOSE_START_UTC <= current_time_utc < MARKET_CLOSE_UTC):
-                    return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
-                            "rationale": f"Avoiding trade during volatile market open/close periods ({current_time_utc} UTC)."}
-
-            except ValueError:
-                rationale += " (Warning: Malformed timestamp, time filters skipped)"
-
-        # --- Initialize signal states ---
-        has_momentum_buy_signal = False
-        has_oversold_buy_signal = False
-
-        # --- 4. Evaluate Enhanced Buy Signals ---
-
-        # Momentum Buy Signal
-        if volume_ratio is not None and \
-           price_change_pct > MOMENTUM_PRICE_CHANGE_THRESHOLD and \
-           volume_ratio > MOMENTUM_VOLUME_RATIO_THRESHOLD:
-            has_momentum_buy_signal = True
-            rationale = f"Momentum BUY: Price change {price_change_pct:.2f}%, Volume {volume_ratio:.2f}x."
-            confidence = CONFIDENCE_BUY_MOMENTUM
-            if current_price >= 10.0:
-                confidence = CONFIDENCE_BUY_STRONG_MOMENTUM
-
-        # Oversold Buy Signal
-        if rsi is not None and rsi < OVERSOLD_RSI_THRESHOLD:
-            has_oversold_buy_signal = True
-            if not has_momentum_buy_signal:
-                rationale = f"Oversold BUY: RSI {rsi:.2f}."
-                confidence = CONFIDENCE_BUY_OVERSOLD
-                if current_price >= 10.0:
-                    confidence = min(CONFIDENCE_BUY_OVERSOLD + 5, 80)
-
-        # --- 5. Decision Logic ---
-        if has_momentum_buy_signal:
-            action = "BUY"
-        elif has_oversold_buy_signal:
-            action = "BUY"
-
-        return {"action": action, "confidence": confidence, "rationale": rationale}

src/strategies/v20260220_210159_evolved.py

@@ -1,97 +0,0 @@
-"""Auto-generated strategy: v20260220_210159
-
-Generated at: 2026-02-20T21:01:59.391523+00:00
-Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
-"""
-
-from __future__ import annotations
-from typing import Any
-from src.strategies.base import BaseStrategy
-
-
-class Strategy_v20260220_210159(BaseStrategy):
-    """Strategy: v20260220_210159"""
-
-    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
-        import datetime
-
-        current_price = market_data.get('current_price')
-        price_change_pct = market_data.get('price_change_pct')
-        volume_ratio = market_data.get('volume_ratio')
-        rsi = market_data.get('rsi')
-        timestamp_str = market_data.get('timestamp')
-        market_name = market_data.get('market')
-
-        # Default action
-        action = "HOLD"
-        confidence = 0
-        rationale = "No strong signal or conditions not met."
-
-        # --- FAILURE PATTERN AVOIDANCE ---
-
-        # 1. Avoid low-priced/penny stocks
-        MIN_PRICE_THRESHOLD = 5.0  # USD
-        if current_price is not None and current_price < MIN_PRICE_THRESHOLD:
-            rationale = (
-                f"HOLD: Stock price (${current_price:.2f}) is below minimum threshold "
-                f"(${MIN_PRICE_THRESHOLD:.2f}). Past failures consistently involved low-priced stocks."
-            )
-            return {"action": action, "confidence": confidence, "rationale": rationale}
-
-        # 2. Avoid early market hour volatility
-        if timestamp_str:
-            try:
-                dt_obj = datetime.datetime.fromisoformat(timestamp_str)
-                utc_hour = dt_obj.hour
-                utc_minute = dt_obj.minute
-
-                if (utc_hour == 14 and utc_minute < 45) or (utc_hour == 13 and utc_minute >= 30):
-                    rationale = (
-                        f"HOLD: Trading during early market hours (UTC {utc_hour}:{utc_minute}), "
-                        f"a period identified with past failures due to high volatility."
-                    )
-                    return {"action": action, "confidence": confidence, "rationale": rationale}
-            except ValueError:
-                pass
-
-        # --- IMPROVED BUY STRATEGY ---
-
-        # Momentum BUY signal
-        if volume_ratio is not None and price_change_pct is not None:
-            if price_change_pct > 7.0 and volume_ratio > 3.0:
-                action = "BUY"
-                confidence = 70
-                rationale = "Improved BUY: Momentum signal with high volume and above price threshold."
-
-                if market_name == 'US_AMEX':
-                    confidence = max(55, confidence - 5)
-                    rationale += " (Adjusted lower for AMEX market's higher risk profile)."
-                elif market_name == 'US_NASDAQ' and price_change_pct > 20:
-                    confidence = max(50, confidence - 10)
-                    rationale += " (Adjusted lower for aggressive NASDAQ momentum volatility)."
-
-                if price_change_pct > 15.0:
-                    confidence = max(50, confidence - 5)
-                    rationale += " (Caution: Very high daily price change, potential for reversal)."
-
-                return {"action": action, "confidence": confidence, "rationale": rationale}
-
-        # Oversold BUY signal
-        if rsi is not None and price_change_pct is not None:
-            if rsi < 30 and price_change_pct < -3.0:
-                action = "BUY"
-                confidence = 65
-                rationale = "Improved BUY: Oversold signal with recent decline and above price threshold."
-
-                if market_name == 'US_AMEX':
-                    confidence = max(50, confidence - 5)
-                    rationale += " (Adjusted lower for AMEX market's higher risk on oversold assets)."
-
-                if price_change_pct < -10.0:
-                    confidence = max(45, confidence - 10)
-                    rationale += " (Caution: Very steep decline, potential falling knife)."
-
-                return {"action": action, "confidence": confidence, "rationale": rationale}
-
-        # If no specific BUY signal, default to HOLD
-        return {"action": action, "confidence": confidence, "rationale": rationale}

src/strategies/v20260220_210244_evolved.py

@@ -1,88 +0,0 @@
-"""Auto-generated strategy: v20260220_210244
-
-Generated at: 2026-02-20T21:02:44.387355+00:00
-Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
-"""
-
-from __future__ import annotations
-from typing import Any
-from src.strategies.base import BaseStrategy
-
-
-class Strategy_v20260220_210244(BaseStrategy):
-    """Strategy: v20260220_210244"""
-
-    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
-        from datetime import datetime
-
-        # Extract required data points safely
-        current_price = market_data.get("current_price")
-        price_change_pct = market_data.get("price_change_pct")
-        volume_ratio = market_data.get("volume_ratio")
-        rsi = market_data.get("rsi")
-        timestamp_str = market_data.get("timestamp")
-        market_name = market_data.get("market")
-        stock_code = market_data.get("stock_code", "UNKNOWN")
-
-        # Default action is HOLD with conservative confidence and rationale
-        action = "HOLD"
-        confidence = 50
-        rationale = f"No strong BUY signal for {stock_code} or awaiting more favorable conditions after avoiding known failure patterns."
-
-        # --- 1. Failure Pattern Avoidance Filters ---
-
-        # A. Avoid low-priced (penny) stocks
-        if current_price is not None and current_price < 5.0:
-            return {
-                "action": "HOLD",
-                "confidence": 50,
-                "rationale": f"AVOID {stock_code}: Stock price (${current_price:.2f}) is below minimum threshold ($5.00) for BUY action. Identified past failures on highly volatile, low-priced stocks."
-            }
-
-        # B. Avoid initiating BUY trades during identified high-volatility hours
-        if timestamp_str:
-            try:
-                trade_hour = datetime.fromisoformat(timestamp_str).hour
-                if trade_hour in [14, 20]:
-                    return {
-                        "action": "HOLD",
-                        "confidence": 50,
-                        "rationale": f"AVOID {stock_code}: Trading during historically volatile hour ({trade_hour} UTC) where previous BUYs resulted in losses. Prefer to observe market stability."
-                    }
-            except ValueError:
-                pass
-
-        # C. Be cautious with extreme momentum spikes
-        if volume_ratio is not None and price_change_pct is not None:
-            if volume_ratio >= 9.0 and price_change_pct >= 15.0:
-                return {
-                    "action": "HOLD",
-                    "confidence": 50,
-                    "rationale": f"AVOID {stock_code}: Extreme short-term momentum detected (price change: +{price_change_pct:.2f}%, volume ratio: {volume_ratio:.1f}x). Historical failures indicate buying into such rapid spikes often leads to reversals."
-                }
-
-        # D. Be cautious with "oversold" signals without further confirmation
-        if rsi is not None and rsi < 30:
-            return {
-                "action": "HOLD",
-                "confidence": 50,
-                "rationale": f"AVOID {stock_code}: Oversold signal (RSI={rsi:.1f}) detected. While often a BUY signal, historical failures on similar 'oversold' trades suggest waiting for stronger confirmation."
-            }
-
-        # --- 2. Improved BUY Signal Generation ---
-        if volume_ratio is not None and 2.0 <= volume_ratio < 9.0 and \
-           price_change_pct is not None and 2.0 <= price_change_pct < 15.0:
-
-            action = "BUY"
-            confidence = 70
-            rationale = f"BUY {stock_code}: Moderate momentum detected (price change: +{price_change_pct:.2f}%, volume ratio: {volume_ratio:.1f}x). Passed filters for price and extreme momentum, avoiding past failure patterns."
-
-            if market_name in ["US_AMEX", "US_NASDAQ"]:
-                confidence = max(60, confidence - 5)
-                rationale += f" Adjusted confidence for {market_name} market characteristics."
-            elif market_name == "US_NYSE":
-                confidence = max(65, confidence)
-
-            confidence = max(50, min(85, confidence))
-
-        return {"action": action, "confidence": confidence, "rationale": rationale}

tests/test_brain.py

@@ -93,9 +93,21 @@ class TestMalformedJsonHandling:
 
     def test_json_with_missing_fields_returns_hold(self, settings):
         client = GeminiClient(settings)
-        decision = client.parse_response('{"action": "BUY"}')
+        raw = '{"action": "BUY"}'
+        decision = client.parse_response(raw)
         assert decision.action == "HOLD"
         assert decision.confidence == 0
+        # rationale preserves raw so prompt_override callers (e.g. pre_market_planner)
+        # can extract non-TradeDecision JSON from decision.rationale (#245)
+        assert decision.rationale == raw
+
+    def test_non_trade_decision_json_preserves_raw_in_rationale(self, settings):
+        """Playbook JSON (no action/confidence/rationale) must be preserved for planner."""
+        client = GeminiClient(settings)
+        playbook_json = '{"market_outlook": "neutral", "stocks": []}'
+        decision = client.parse_response(playbook_json)
+        assert decision.action == "HOLD"
+        assert decision.rationale == playbook_json
 
     def test_json_with_invalid_action_returns_hold(self, settings):
         client = GeminiClient(settings)
@@ -290,9 +302,10 @@ class TestPromptOverride:
         client = GeminiClient(settings)
 
         custom_prompt = "You are a playbook generator. Return JSON with scenarios."
+        playbook_json = '{"market_outlook": "neutral", "stocks": []}'
 
         mock_response = MagicMock()
-        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "test"}'
+        mock_response.text = playbook_json
 
         with patch.object(
             client._client.aio.models,
@@ -305,7 +318,7 @@ class TestPromptOverride:
                 "current_price": 0,
                 "prompt_override": custom_prompt,
             }
-            await client.decide(market_data)
+            decision = await client.decide(market_data)
 
             # Verify the custom prompt was sent, not a built prompt
             mock_generate.assert_called_once()
@@ -313,17 +326,50 @@ class TestPromptOverride:
                 "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
             )
             assert actual_prompt == custom_prompt
+            # Raw response preserved in rationale without parse_response (#247)
+            assert decision.rationale == playbook_json
 
     @pytest.mark.asyncio
-    async def test_prompt_override_skips_optimization(self, settings):
+    async def test_prompt_override_skips_parse_response(self, settings):
-        """prompt_override should bypass prompt optimization."""
+        """prompt_override bypasses parse_response — no Missing fields warning, raw preserved."""
         client = GeminiClient(settings)
         client._enable_optimization = True
 
         custom_prompt = "Custom playbook prompt"
+        playbook_json = '{"market_outlook": "bullish", "stocks": [{"stock_code": "AAPL"}]}'
 
         mock_response = MagicMock()
-        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+        mock_response.text = playbook_json
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ):
+            with patch.object(client, "parse_response") as mock_parse:
+                market_data = {
+                    "stock_code": "PLANNER",
+                    "current_price": 0,
+                    "prompt_override": custom_prompt,
+                }
+                decision = await client.decide(market_data)
+
+                # parse_response must NOT be called for prompt_override
+                mock_parse.assert_not_called()
+                # Raw playbook JSON preserved in rationale
+                assert decision.rationale == playbook_json
+
+    @pytest.mark.asyncio
+    async def test_prompt_override_takes_priority_over_optimization(self, settings):
+        """prompt_override must win over enable_optimization=True."""
+        client = GeminiClient(settings)
+        client._enable_optimization = True
+
+        custom_prompt = "Explicit playbook prompt"
+
+        mock_response = MagicMock()
+        mock_response.text = '{"market_outlook": "neutral", "stocks": []}'
 
         with patch.object(
             client._client.aio.models,
@@ -341,6 +387,7 @@ class TestPromptOverride:
             actual_prompt = mock_generate.call_args[1].get(
                 "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
             )
+            # The custom prompt must be used, not the compressed prompt
             assert actual_prompt == custom_prompt
 
     @pytest.mark.asyncio

tests/test_broker.py

@@ -354,6 +354,8 @@ class TestFetchMarketRankings:
         assert "ranking/fluctuation" in url
         assert headers.get("tr_id") == "FHPST01700000"
         assert params.get("fid_cond_scr_div_code") == "20170"
+        # 실전 API는 4자리("0000") 거부 — 1자리("0")여야 한다 (#240)
+        assert params.get("fid_rank_sort_cls_code") == "0"
 
     @pytest.mark.asyncio
     async def test_volume_returns_parsed_rows(self, broker: KISBroker) -> None:
@@ -376,6 +378,27 @@ class TestFetchMarketRankings:
         assert result[0]["price"] == 75000.0
         assert result[0]["change_rate"] == 2.5
 
+    @pytest.mark.asyncio
+    async def test_fluctuation_parses_stck_shrn_iscd(self, broker: KISBroker) -> None:
+        """실전 API는 mksc_shrn_iscd 대신 stck_shrn_iscd를 반환한다 (#240)."""
+        items = [
+            {
+                "stck_shrn_iscd": "015260",
+                "hts_kor_isnm": "에이엔피",
+                "stck_prpr": "794",
+                "acml_vol": "4896196",
+                "prdy_ctrt": "29.74",
+                "vol_inrt": "0",
+            }
+        ]
+        mock_resp = _make_ranking_mock(items)
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp):
+            result = await broker.fetch_market_rankings(ranking_type="fluctuation")
+
+        assert len(result) == 1
+        assert result[0]["stock_code"] == "015260"
+        assert result[0]["change_rate"] == 29.74
+
 
 # ---------------------------------------------------------------------------
 # KRX tick unit / round-down helpers (issue #157)

tests/test_dashboard.py

@@ -413,3 +413,39 @@ def test_status_circuit_breaker_unknown_when_no_data(tmp_path: Path) -> None:
     cb = body["circuit_breaker"]
     assert cb["status"] == "unknown"
     assert cb["current_pnl_pct"] is None
+
+
+def test_status_mode_paper(tmp_path: Path) -> None:
+    """mode=paper로 생성하면 status 응답에 mode=paper가 포함돼야 한다."""
+    db_path = tmp_path / "dashboard_test.db"
+    conn = init_db(str(db_path))
+    _seed_db(conn)
+    conn.close()
+    app = create_dashboard_app(str(db_path), mode="paper")
+    get_status = _endpoint(app, "/api/status")
+    body = get_status()
+    assert body["mode"] == "paper"
+
+
+def test_status_mode_live(tmp_path: Path) -> None:
+    """mode=live로 생성하면 status 응답에 mode=live가 포함돼야 한다."""
+    db_path = tmp_path / "dashboard_test.db"
+    conn = init_db(str(db_path))
+    _seed_db(conn)
+    conn.close()
+    app = create_dashboard_app(str(db_path), mode="live")
+    get_status = _endpoint(app, "/api/status")
+    body = get_status()
+    assert body["mode"] == "live"
+
+
+def test_status_mode_default_paper(tmp_path: Path) -> None:
+    """mode 파라미터 미전달 시 기본값은 paper여야 한다."""
+    db_path = tmp_path / "dashboard_test.db"
+    conn = init_db(str(db_path))
+    _seed_db(conn)
+    conn.close()
+    app = create_dashboard_app(str(db_path))
+    get_status = _endpoint(app, "/api/status")
+    body = get_status()
+    assert body["mode"] == "paper"

tests/test_main.py

@@ -15,6 +15,7 @@ from src.logging.decision_logger import DecisionLogger
 from src.main import (
     _apply_dashboard_flag,
     _determine_order_quantity,
+    _extract_avg_price_from_balance,
     _extract_held_codes_from_balance,
     _extract_held_qty_from_balance,
     _handle_market_close,
@@ -76,6 +77,81 @@ def _make_sell_match(stock_code: str = "005930") -> ScenarioMatch:
     )
 
 
+class TestExtractAvgPriceFromBalance:
+    """Tests for _extract_avg_price_from_balance() (issue #249)."""
+
+    def test_domestic_returns_pchs_avg_pric(self) -> None:
+        """Domestic balance with pchs_avg_pric returns the correct float."""
+        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": "68000.00"}]}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 68000.0
+
+    def test_overseas_returns_pchs_avg_pric(self) -> None:
+        """Overseas balance with pchs_avg_pric returns the correct float."""
+        balance = {"output1": [{"ovrs_pdno": "AAPL", "pchs_avg_pric": "170.50"}]}
+        result = _extract_avg_price_from_balance(balance, "AAPL", is_domestic=False)
+        assert result == 170.5
+
+    def test_returns_zero_when_field_absent(self) -> None:
+        """Returns 0.0 when pchs_avg_pric key is missing entirely."""
+        balance = {"output1": [{"pdno": "005930", "ord_psbl_qty": "5"}]}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_returns_zero_when_field_empty_string(self) -> None:
+        """Returns 0.0 when pchs_avg_pric is an empty string."""
+        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": ""}]}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_returns_zero_when_stock_not_found(self) -> None:
+        """Returns 0.0 when the requested stock_code is not in output1."""
+        balance = {"output1": [{"pdno": "000660", "pchs_avg_pric": "100000.0"}]}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_returns_zero_when_output1_empty(self) -> None:
+        """Returns 0.0 when output1 is an empty list."""
+        balance = {"output1": []}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_returns_zero_when_output1_key_absent(self) -> None:
+        """Returns 0.0 when output1 key is missing from balance_data."""
+        balance: dict = {}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_handles_output1_as_dict(self) -> None:
+        """Handles the edge case where output1 is a dict instead of a list."""
+        balance = {"output1": {"pdno": "005930", "pchs_avg_pric": "55000.0"}}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 55000.0
+
+    def test_case_insensitive_code_matching(self) -> None:
+        """Stock code comparison is case-insensitive."""
+        balance = {"output1": [{"ovrs_pdno": "aapl", "pchs_avg_pric": "170.0"}]}
+        result = _extract_avg_price_from_balance(balance, "AAPL", is_domestic=False)
+        assert result == 170.0
+
+    def test_returns_zero_for_non_numeric_string(self) -> None:
+        """Returns 0.0 when pchs_avg_pric contains a non-numeric value."""
+        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": "N/A"}]}
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 0.0
+
+    def test_returns_correct_stock_among_multiple(self) -> None:
+        """Returns only the avg price of the requested stock when output1 has multiple holdings."""
+        balance = {
+            "output1": [
+                {"pdno": "000660", "pchs_avg_pric": "150000.0"},
+                {"pdno": "005930", "pchs_avg_pric": "68000.0"},
+            ]
+        }
+        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
+        assert result == 68000.0
+
+
 class TestExtractHeldQtyFromBalance:
     """Tests for _extract_held_qty_from_balance()."""
 
@@ -101,10 +177,24 @@ class TestExtractHeldQtyFromBalance:
         balance = {"output1": [], "output2": [{}]}
         assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 0
 
-    def test_overseas_returns_ovrs_cblc_qty(self) -> None:
+    def test_overseas_returns_ord_psbl_qty_first(self) -> None:
+        """ord_psbl_qty (주문가능수량) takes priority over ovrs_cblc_qty."""
+        balance = {
+            "output1": [{"ovrs_pdno": "AAPL", "ord_psbl_qty": "8", "ovrs_cblc_qty": "10"}]
+        }
+        assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 8
+
+    def test_overseas_fallback_to_ovrs_cblc_qty_when_ord_psbl_qty_absent(self) -> None:
         balance = {"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}]}
         assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 10
 
+    def test_overseas_returns_zero_when_ord_psbl_qty_zero(self) -> None:
+        """Expired/delisted securities: ovrs_cblc_qty large but ord_psbl_qty=0."""
+        balance = {
+            "output1": [{"ovrs_pdno": "MLECW", "ord_psbl_qty": "0", "ovrs_cblc_qty": "289456"}]
+        }
+        assert _extract_held_qty_from_balance(balance, "MLECW", is_domestic=False) == 0
+
     def test_overseas_fallback_to_hldg_qty(self) -> None:
         balance = {"output1": [{"ovrs_pdno": "AAPL", "hldg_qty": "4"}]}
         assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 4
@@ -147,6 +237,26 @@ class TestExtractHeldCodesFromBalance:
         result = _extract_held_codes_from_balance(balance, is_domestic=False)
         assert result == ["AAPL"]
 
+    def test_overseas_uses_ord_psbl_qty_to_filter(self) -> None:
+        """ord_psbl_qty=0 should exclude stock even if ovrs_cblc_qty is large."""
+        balance = {
+            "output1": [
+                {"ovrs_pdno": "MLECW", "ord_psbl_qty": "0", "ovrs_cblc_qty": "289456"},
+                {"ovrs_pdno": "AAPL", "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"},
+            ]
+        }
+        result = _extract_held_codes_from_balance(balance, is_domestic=False)
+        assert "MLECW" not in result
+        assert "AAPL" in result
+
+    def test_overseas_includes_stock_when_ord_psbl_qty_absent_and_ovrs_cblc_qty_positive(
+        self,
+    ) -> None:
+        """Fallback to ovrs_cblc_qty when ord_psbl_qty field is missing."""
+        balance = {"output1": [{"ovrs_pdno": "TSLA", "ovrs_cblc_qty": "3"}]}
+        result = _extract_held_codes_from_balance(balance, is_domestic=False)
+        assert "TSLA" in result
+
 
 class TestDetermineOrderQuantity:
     """Test _determine_order_quantity() — SELL uses broker_held_qty."""
@@ -1136,7 +1246,8 @@ class TestOverseasBalanceParsing:
         mock_overseas_broker_with_buy_scenario.send_overseas_order.assert_called_once()
         call_kwargs = mock_overseas_broker_with_buy_scenario.send_overseas_order.call_args
         sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
-        expected_price = round(182.5 * 1.002, 4)  # 0.2% premium for BUY limit orders
+        # KIS requires max 2 decimal places for prices >= $1 (#252)
+        expected_price = round(182.5 * 1.002, 2)  # 0.2% premium for BUY limit orders
         assert sent_price == expected_price, (
             f"Expected limit price {expected_price} (182.5 * 1.002) but got {sent_price}. "
             "BUY uses +0.2% to improve fill rate while minimising overpayment (#211)."
@@ -1215,12 +1326,133 @@ class TestOverseasBalanceParsing:
         overseas_broker.send_overseas_order.assert_called_once()
         call_kwargs = overseas_broker.send_overseas_order.call_args
         sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
-        expected_price = round(sell_price * 0.998, 4)  # -0.2% for SELL limit orders
+        # KIS requires max 2 decimal places for prices >= $1 (#252)
+        expected_price = round(sell_price * 0.998, 2)  # -0.2% for SELL limit orders
         assert sent_price == expected_price, (
             f"Expected SELL limit price {expected_price} (182.5 * 0.998) but got {sent_price}. "
             "SELL uses -0.2% to ensure fill even when price dips slightly (#211)."
         )
 
+    @pytest.mark.asyncio
+    async def test_overseas_buy_price_rounded_to_2_decimals_for_dollar_plus_stock(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_playbook: DayPlaybook,
+        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:
+        """BUY price for $1+ stocks is rounded to 2 decimal places (issue #252).
+
+        KIS rejects prices with more than 2 decimal places for stocks priced >= $1.
+        current_price=50.1234 * 1.002 = 50.22... should be sent as 50.22, not 50.2236.
+        """
+        overseas_broker = MagicMock()
+        overseas_broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output1": [],
+                "output2": [{"frcr_evlu_tota": "0", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "0"}],
+            }
+        )
+        overseas_broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "50.1234", "rate": "0"}}
+        )
+        overseas_broker.send_overseas_order = AsyncMock(
+            return_value={"rt_cd": None, "msg1": "주문접수"}
+        )
+
+        db_conn = init_db(":memory:")
+        decision_logger = DecisionLogger(db_conn)
+
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match())
+
+        await trading_cycle(
+            broker=mock_domestic_broker,
+            overseas_broker=overseas_broker,
+            scenario_engine=engine,
+            playbook=mock_playbook,
+            risk=mock_risk,
+            db_conn=db_conn,
+            decision_logger=decision_logger,
+            context_store=mock_context_store,
+            criticality_assessor=mock_criticality_assessor,
+            telegram=mock_telegram,
+            market=mock_overseas_market,
+            stock_code="TQQQ",
+            scan_candidates={},
+        )
+
+        overseas_broker.send_overseas_order.assert_called_once()
+        sent_price = overseas_broker.send_overseas_order.call_args[1].get("price") or \
+            overseas_broker.send_overseas_order.call_args[0][4]
+        # 50.1234 * 1.002 = 50.2235... rounded to 2 decimals = 50.22
+        assert sent_price == round(50.1234 * 1.002, 2), (
+            f"Expected 2-decimal price {round(50.1234 * 1.002, 2)} but got {sent_price} (#252)"
+        )
+
+    @pytest.mark.asyncio
+    async def test_overseas_penny_stock_price_keeps_4_decimals(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_playbook: DayPlaybook,
+        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:
+        """BUY price for penny stocks (< $1) uses 4 decimal places (issue #252)."""
+        overseas_broker = MagicMock()
+        overseas_broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output1": [],
+                "output2": [{"frcr_evlu_tota": "0", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "0"}],
+            }
+        )
+        overseas_broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "0.5678", "rate": "0"}}
+        )
+        overseas_broker.send_overseas_order = AsyncMock(
+            return_value={"rt_cd": None, "msg1": "주문접수"}
+        )
+
+        db_conn = init_db(":memory:")
+        decision_logger = DecisionLogger(db_conn)
+
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match())
+
+        await trading_cycle(
+            broker=mock_domestic_broker,
+            overseas_broker=overseas_broker,
+            scenario_engine=engine,
+            playbook=mock_playbook,
+            risk=mock_risk,
+            db_conn=db_conn,
+            decision_logger=decision_logger,
+            context_store=mock_context_store,
+            criticality_assessor=mock_criticality_assessor,
+            telegram=mock_telegram,
+            market=mock_overseas_market,
+            stock_code="PENNYX",
+            scan_candidates={},
+        )
+
+        overseas_broker.send_overseas_order.assert_called_once()
+        sent_price = overseas_broker.send_overseas_order.call_args[1].get("price") or \
+            overseas_broker.send_overseas_order.call_args[0][4]
+        # 0.5678 * 1.002 = 0.56893... rounded to 4 decimals = 0.5689
+        assert sent_price == round(0.5678 * 1.002, 4), (
+            f"Expected 4-decimal price {round(0.5678 * 1.002, 4)} but got {sent_price} (#252)"
+        )
+
 
 class TestScenarioEngineIntegration:
     """Test scenario engine integration in trading_cycle."""
@@ -2014,6 +2246,92 @@ async def test_hold_not_overridden_when_between_stop_loss_and_take_profit() -> N
     broker.send_order.assert_not_called()
 
 
+@pytest.mark.asyncio
+async def test_stop_loss_not_triggered_when_current_price_is_zero() -> None:
+    """HOLD must stay HOLD when current_price=0 even if entry_price is set (issue #251).
+
+    A price API failure that returns 0.0 must not cause a false -100% stop-loss.
+    """
+    db_conn = init_db(":memory:")
+    decision_logger = DecisionLogger(db_conn)
+
+    buy_decision_id = decision_logger.log_decision(
+        stock_code="005930",
+        market="KR",
+        exchange_code="KRX",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        context_snapshot={},
+        input_data={},
+    )
+    log_trade(
+        conn=db_conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        quantity=1,
+        price=100.0,  # valid entry price
+        market="KR",
+        exchange_code="KRX",
+        decision_id=buy_decision_id,
+    )
+
+    broker = MagicMock()
+    # Price API returns 0.0 — simulates API failure or pre-market unavailability
+    broker.get_current_price = AsyncMock(return_value=(0.0, 0.0, 0.0))
+    broker.get_balance = AsyncMock(
+        return_value={
+            "output2": [
+                {
+                    "tot_evlu_amt": "100000",
+                    "dnca_tot_amt": "10000",
+                    "pchs_amt_smtl_amt": "90000",
+                }
+            ]
+        }
+    )
+    broker.send_order = AsyncMock(return_value={"msg1": "OK"})
+
+    market = MagicMock()
+    market.name = "Korea"
+    market.code = "KR"
+    market.exchange_code = "KRX"
+    market.is_domestic = True
+
+    telegram = MagicMock()
+    telegram.notify_trade_execution = AsyncMock()
+    telegram.notify_fat_finger = AsyncMock()
+    telegram.notify_circuit_breaker = AsyncMock()
+    telegram.notify_scenario_matched = AsyncMock()
+
+    await trading_cycle(
+        broker=broker,
+        overseas_broker=MagicMock(),
+        scenario_engine=MagicMock(evaluate=MagicMock(return_value=_make_hold_match())),
+        playbook=_make_playbook("KR"),
+        risk=MagicMock(),
+        db_conn=db_conn,
+        decision_logger=decision_logger,
+        context_store=MagicMock(
+            get_latest_timeframe=MagicMock(return_value=None),
+            set_context=MagicMock(),
+        ),
+        criticality_assessor=MagicMock(
+            assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+            get_timeout=MagicMock(return_value=5.0),
+        ),
+        telegram=telegram,
+        market=market,
+        stock_code="005930",
+        scan_candidates={},
+    )
+
+    # No SELL order must be placed — current_price=0 must suppress stop-loss
+    broker.send_order.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_sell_order_uses_broker_balance_qty_not_db() -> None:
     """SELL quantity must come from broker balance output1, not DB.
@@ -3784,6 +4102,70 @@ class TestSyncPositionsFromBroker:
         # Two distinct exchange codes (NASD, NYSE) → 2 calls
         assert overseas_broker.get_overseas_balance.call_count == 2
 
+    @pytest.mark.asyncio
+    async def test_syncs_domestic_position_with_correct_avg_price(self) -> None:
+        """Domestic position is stored with pchs_avg_pric as price (issue #249)."""
+        settings = self._make_settings("KR")
+        db_conn = init_db(":memory:")
+
+        balance = {
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "5", "pchs_avg_pric": "68000.0"}],
+            "output2": [{"tot_evlu_amt": "1000000", "dnca_tot_amt": "500000", "pchs_amt_smtl_amt": "500000"}],
+        }
+        broker = MagicMock()
+        broker.get_balance = AsyncMock(return_value=balance)
+        overseas_broker = MagicMock()
+
+        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
+
+        from src.db import get_open_position
+        pos = get_open_position(db_conn, "005930", "KR")
+        assert pos is not None
+        assert pos["price"] == 68000.0
+
+    @pytest.mark.asyncio
+    async def test_syncs_overseas_position_with_correct_avg_price(self) -> None:
+        """Overseas position is stored with pchs_avg_pric as price (issue #249)."""
+        settings = self._make_settings("US_NASDAQ")
+        db_conn = init_db(":memory:")
+
+        balance = {
+            "output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10", "pchs_avg_pric": "170.0"}],
+            "output2": [{"frcr_evlu_tota": "50000", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "40000"}],
+        }
+        broker = MagicMock()
+        overseas_broker = MagicMock()
+        overseas_broker.get_overseas_balance = AsyncMock(return_value=balance)
+
+        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
+
+        from src.db import get_open_position
+        pos = get_open_position(db_conn, "AAPL", "US_NASDAQ")
+        assert pos is not None
+        assert pos["price"] == 170.0
+
+    @pytest.mark.asyncio
+    async def test_syncs_position_with_zero_price_when_pchs_avg_pric_absent(self) -> None:
+        """Fallback to price=0.0 when pchs_avg_pric is absent (issue #249)."""
+        settings = self._make_settings("KR")
+        db_conn = init_db(":memory:")
+
+        # No pchs_avg_pric in output1
+        balance = {
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "5"}],
+            "output2": [{"tot_evlu_amt": "1000000", "dnca_tot_amt": "500000", "pchs_amt_smtl_amt": "500000"}],
+        }
+        broker = MagicMock()
+        broker.get_balance = AsyncMock(return_value=balance)
+        overseas_broker = MagicMock()
+
+        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
+
+        from src.db import get_open_position
+        pos = get_open_position(db_conn, "005930", "KR")
+        assert pos is not None
+        assert pos["price"] == 0.0
+
 
 # ---------------------------------------------------------------------------
 # Domestic BUY double-prevention (issue #206) — trading_cycle integration
@@ -4378,3 +4760,189 @@ class TestDomesticLimitOrderPrice:
         expected_price = kr_round_down(current_price * 0.998)
         assert call_kwargs["price"] == expected_price
         assert call_kwargs["order_type"] == "SELL"
+
+
+# ---------------------------------------------------------------------------
+# Ghost position — overseas SELL "잔고내역이 없습니다" handling
+# ---------------------------------------------------------------------------
+
+
+class TestOverseasGhostPositionClose:
+    """trading_cycle must close ghost DB position when broker returns 잔고없음."""
+
+    def _make_overseas_market(self) -> MagicMock:
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+        return market
+
+    def _make_overseas_broker(
+        self,
+        current_price: float,
+        balance_data: dict,
+        sell_result: dict,
+    ) -> MagicMock:
+        ob = MagicMock()
+        ob.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": str(current_price), "rate": "0.0"}}
+        )
+        ob.get_overseas_balance = AsyncMock(return_value=balance_data)
+        ob.send_overseas_order = AsyncMock(return_value=sell_result)
+        return ob
+
+    @pytest.mark.asyncio
+    async def test_ghost_position_closes_db_on_no_balance_error(self) -> None:
+        """When SELL fails with '잔고내역이 없습니다', log_trade is called to close the ghost.
+
+        This can happen when exchange code recorded at startup differs from the
+        exchange code used in the SELL cycle (e.g. KNRX recorded as NASD but
+        actually traded on AMEX), causing the broker to see no matching balance.
+        The position has ord_psbl_qty > 0 (so a SELL is attempted), but KIS
+        rejects it with '잔고내역이 없습니다'.
+        """
+        from src.strategy.models import ScenarioAction
+
+        stock_code = "KNRX"
+        current_price = 1.5
+        # ord_psbl_qty=5 means the code passes the qty check and a SELL is sent
+        balance_data = {
+            "output1": [
+                {"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}
+            ],
+            "output2": [{"tot_evlu_amt": "10000", "frcr_dncl_amt_2": "10000"}],
+        }
+        sell_result = {"rt_cd": "1", "msg1": "모의투자 잔고내역이 없습니다"}
+
+        domestic_broker = MagicMock()
+        domestic_broker.get_balance = AsyncMock(return_value={"output1": [], "output2": [{}]})
+        overseas_broker = self._make_overseas_broker(current_price, balance_data, sell_result)
+        market = self._make_overseas_market()
+
+        sell_match = ScenarioMatch(
+            stock_code=stock_code,
+            matched_scenario=None,
+            action=ScenarioAction.SELL,
+            confidence=85,
+            rationale="test ghost KNRX",
+        )
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=sell_match)
+
+        risk = MagicMock()
+        risk.validate_order = MagicMock()
+        risk.check_circuit_breaker = MagicMock()
+        telegram = MagicMock()
+        telegram.notify_trade_execution = AsyncMock()
+        telegram.notify_fat_finger = AsyncMock()
+        telegram.notify_circuit_breaker = AsyncMock()
+        telegram.notify_scenario_matched = AsyncMock()
+
+        db_conn = MagicMock()
+
+        settings = MagicMock(spec=Settings)
+        settings.MODE = "paper"
+        settings.POSITION_SIZING_ENABLED = False
+        settings.PAPER_OVERSEAS_CASH = 0
+
+        with patch("src.main.log_trade") as mock_log_trade, patch(
+            "src.main.get_open_position", return_value=None
+        ), patch("src.main.get_latest_buy_trade", return_value=None):
+            await trading_cycle(
+                broker=domestic_broker,
+                overseas_broker=overseas_broker,
+                scenario_engine=engine,
+                playbook=_make_playbook(market="US_NASDAQ"),
+                risk=risk,
+                db_conn=db_conn,
+                decision_logger=MagicMock(),
+                context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
+                criticality_assessor=MagicMock(
+                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+                    get_timeout=MagicMock(return_value=5.0),
+                ),
+                telegram=telegram,
+                market=market,
+                stock_code=stock_code,
+                scan_candidates={},
+                settings=settings,
+            )
+
+        # log_trade must be called with action="SELL" to close the ghost position
+        ghost_close_calls = [
+            c
+            for c in mock_log_trade.call_args_list
+            if c.kwargs.get("action") == "SELL"
+            and "[ghost-close]" in (c.kwargs.get("rationale") or "")
+        ]
+        assert ghost_close_calls, "Expected ghost-close log_trade call was not made"
+
+    @pytest.mark.asyncio
+    async def test_normal_sell_failure_does_not_close_db(self) -> None:
+        """Non-잔고없음 SELL failures must NOT close the DB position."""
+        from src.strategy.models import ScenarioAction
+
+        stock_code = "TSLA"
+        current_price = 250.0
+        balance_data = {
+            "output1": [{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}],
+            "output2": [{"tot_evlu_amt": "100000", "frcr_dncl_amt_2": "100000"}],
+        }
+        sell_result = {"rt_cd": "1", "msg1": "일시적 오류가 발생했습니다"}
+
+        domestic_broker = MagicMock()
+        domestic_broker.get_balance = AsyncMock(return_value={"output1": [], "output2": [{}]})
+        overseas_broker = self._make_overseas_broker(current_price, balance_data, sell_result)
+        market = self._make_overseas_market()
+
+        sell_match = ScenarioMatch(
+            stock_code=stock_code,
+            matched_scenario=None,
+            action=ScenarioAction.SELL,
+            confidence=85,
+            rationale="test",
+        )
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=sell_match)
+
+        risk = MagicMock()
+        risk.validate_order = MagicMock()
+        risk.check_circuit_breaker = MagicMock()
+        telegram = MagicMock()
+        telegram.notify_trade_execution = AsyncMock()
+        telegram.notify_fat_finger = AsyncMock()
+        telegram.notify_circuit_breaker = AsyncMock()
+        telegram.notify_scenario_matched = AsyncMock()
+
+        db_conn = MagicMock()
+
+        with patch("src.main.log_trade") as mock_log_trade, patch(
+            "src.main.get_open_position", return_value=None
+        ):
+            await trading_cycle(
+                broker=domestic_broker,
+                overseas_broker=overseas_broker,
+                scenario_engine=engine,
+                playbook=_make_playbook(market="US_NASDAQ"),
+                risk=risk,
+                db_conn=db_conn,
+                decision_logger=MagicMock(),
+                context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
+                criticality_assessor=MagicMock(
+                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
+                    get_timeout=MagicMock(return_value=5.0),
+                ),
+                telegram=telegram,
+                market=market,
+                stock_code=stock_code,
+                scan_candidates={},
+            )
+
+        ghost_close_calls = [
+            c
+            for c in mock_log_trade.call_args_list
+            if c.kwargs.get("action") == "SELL"
+            and "[ghost-close]" in (c.kwargs.get("rationale") or "")
+        ]
+        assert not ghost_close_calls, "Ghost-close must NOT be triggered for non-잔고없음 errors"

tests/test_overseas_broker.py

@@ -122,9 +122,10 @@ class TestFetchOverseasRankings:
         params = call_args[1]["params"]
 
         assert "/uapi/overseas-stock/v1/ranking/updown-rate" in url
+        assert params["KEYB"] == ""  # Required by KIS API spec
         assert params["EXCD"] == "NAS"
         assert params["NDAY"] == "0"
-        assert params["GUBN"] == "1"
+        assert params["GUBN"] == "1"  # 1=상승율 — 변동성 스캐너는 급등 종목 우선
         assert params["VOL_RANG"] == "0"
 
         overseas_broker._broker._auth_headers.assert_called_with("HHDFS76290000")
@@ -157,6 +158,7 @@ class TestFetchOverseasRankings:
         params = call_args[1]["params"]
 
         assert "/uapi/overseas-stock/v1/ranking/volume-surge" in url
+        assert params["KEYB"] == ""  # Required by KIS API spec
         assert params["EXCD"] == "NYS"
         assert params["MIXN"] == "0"
         assert params["VOL_RANG"] == "0"

tests/test_token_efficiency.py

@@ -124,6 +124,10 @@ class TestPromptOptimizer:
         assert len(prompt) < 300
         assert "005930" in prompt
         assert "75000" in prompt
+        # Keys must match parse_response expectations (#242)
+        assert '"action"' in prompt
+        assert '"confidence"' in prompt
+        assert '"rationale"' in prompt
 
     def test_build_compressed_prompt_no_instructions(self):
         """Test compressed prompt without instructions."""