feat: use playbook allocation_pct in position sizing (#172)

- Add playbook_allocation_pct and scenario_confidence parameters to
  _determine_order_quantity() with playbook-based sizing taking priority
  over volatility-score fallback when provided
- Confidence scaling: confidence/80 multiplier (confidence 96 → 1.2x)
  clipped to [POSITION_MIN_ALLOCATION_PCT, POSITION_MAX_ALLOCATION_PCT]
- Pass matched_scenario.allocation_pct and match.confidence from
  trading_cycle so AI's allocation decisions reach order execution
- Add 4 new tests: playbook priority, confidence scaling, max clamp,
  and fallback behavior

Closes #172

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

src/config.py

@@ -93,6 +93,16 @@ class Settings(BaseSettings):
     TELEGRAM_COMMANDS_ENABLED: bool = True
     TELEGRAM_POLLING_INTERVAL: float = 1.0  # seconds
 
+    # Telegram notification type filters (granular control)
+    # circuit_breaker is always sent regardless — safety-critical
+    TELEGRAM_NOTIFY_TRADES: bool = True           # BUY/SELL execution alerts
+    TELEGRAM_NOTIFY_MARKET_OPEN_CLOSE: bool = True  # Market open/close alerts
+    TELEGRAM_NOTIFY_FAT_FINGER: bool = True       # Fat-finger rejection alerts
+    TELEGRAM_NOTIFY_SYSTEM_EVENTS: bool = True    # System start/shutdown alerts
+    TELEGRAM_NOTIFY_PLAYBOOK: bool = True         # Playbook generated/failed alerts
+    TELEGRAM_NOTIFY_SCENARIO_MATCH: bool = True   # Scenario matched alerts (most frequent)
+    TELEGRAM_NOTIFY_ERRORS: bool = True           # Error alerts
+
     # Overseas ranking API (KIS endpoint/TR_ID may vary by account/product)
     # Override these from .env if your account uses different specs.
     OVERSEAS_RANKING_ENABLED: bool = True

src/main.py

@@ -41,7 +41,7 @@ from src.evolution.optimizer import EvolutionOptimizer
 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, TelegramCommandHandler
+from src.notifications.telegram_client import NotificationFilter, TelegramClient, TelegramCommandHandler
 from src.strategy.models import DayPlaybook
 from src.strategy.playbook_store import PlaybookStore
 from src.strategy.pre_market_planner import PreMarketPlanner
@@ -106,6 +106,82 @@ def _extract_symbol_from_holding(item: dict[str, Any]) -> str:
     return ""
 
 
+def _extract_held_codes_from_balance(
+    balance_data: dict[str, Any],
+    *,
+    is_domestic: bool,
+) -> list[str]:
+    """Return stock codes with a positive orderable quantity from a balance response.
+
+    Uses the broker's live output1 as the source of truth so that partial fills
+    and manual external trades are always reflected correctly.
+    """
+    output1 = balance_data.get("output1", [])
+    if isinstance(output1, dict):
+        output1 = [output1]
+    if not isinstance(output1, list):
+        return []
+
+    codes: list[str] = []
+    for holding in output1:
+        if not isinstance(holding, dict):
+            continue
+        code_key = "pdno" if is_domestic else "ovrs_pdno"
+        code = str(holding.get(code_key, "")).strip().upper()
+        if not code:
+            continue
+        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)
+        if qty > 0:
+            codes.append(code)
+    return codes
+
+
+def _extract_held_qty_from_balance(
+    balance_data: dict[str, Any],
+    stock_code: str,
+    *,
+    is_domestic: bool,
+) -> int:
+    """Extract the broker-confirmed orderable quantity for a stock.
+
+    Uses the broker's live balance response (output1) as the source of truth
+    rather than the local DB, because DB records reflect order quantity which
+    may differ from actual fill quantity due to partial fills.
+
+    Domestic fields (VTTC8434R output1):
+        pdno          — 종목코드
+        ord_psbl_qty  — 주문가능수량 (preferred: excludes unsettled)
+        hldg_qty      — 보유수량 (fallback)
+
+    Overseas fields (output1):
+        ovrs_pdno     — 종목코드
+        ovrs_cblc_qty — 해외잔고수량 (preferred)
+        hldg_qty      — 보유수량 (fallback)
+    """
+    output1 = balance_data.get("output1", [])
+    if isinstance(output1, dict):
+        output1 = [output1]
+    if not isinstance(output1, list):
+        return 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
+        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)
+        return qty
+    return 0
+
+
 def _determine_order_quantity(
     *,
     action: str,
@@ -113,16 +189,40 @@ def _determine_order_quantity(
     total_cash: float,
     candidate: ScanCandidate | None,
     settings: Settings | None,
+    broker_held_qty: int = 0,
+    playbook_allocation_pct: float | None = None,
+    scenario_confidence: int = 80,
 ) -> int:
-    """Determine order quantity using volatility-aware position sizing."""
+    """Determine order quantity using volatility-aware position sizing.
-    if action != "BUY":
+
-        return 1
+    Priority:
+    1. playbook_allocation_pct (AI-specified) scaled by scenario_confidence
+    2. Fallback: volatility-score-based allocation from scanner candidate
+    """
+    if action == "SELL":
+        return broker_held_qty
     if current_price <= 0 or total_cash <= 0:
         return 0
 
     if settings is None or not settings.POSITION_SIZING_ENABLED:
         return 1
 
+    # Use AI-specified allocation_pct if available
+    if playbook_allocation_pct is not None:
+        # Confidence scaling: confidence 80 → 1.0x, confidence 95 → 1.19x
+        confidence_scale = scenario_confidence / 80.0
+        effective_pct = min(
+            settings.POSITION_MAX_ALLOCATION_PCT,
+            max(
+                settings.POSITION_MIN_ALLOCATION_PCT,
+                playbook_allocation_pct * confidence_scale,
+            ),
+        )
+        budget = total_cash * (effective_pct / 100.0)
+        quantity = int(budget // current_price)
+        return max(0, quantity)
+
+    # Fallback: volatility-score-based allocation
     target_score = max(1.0, settings.POSITION_VOLATILITY_TARGET_SCORE)
     observed_score = candidate.score if candidate else target_score
     observed_score = max(1.0, min(100.0, observed_score))
@@ -387,8 +487,10 @@ async def trading_cycle(
             if entry_price > 0:
                 loss_pct = (current_price - entry_price) / entry_price * 100
                 stop_loss_threshold = -2.0
+                take_profit_threshold = 3.0
                 if stock_playbook and stock_playbook.scenarios:
                     stop_loss_threshold = stock_playbook.scenarios[0].stop_loss_pct
+                    take_profit_threshold = stock_playbook.scenarios[0].take_profit_pct
 
                 if loss_pct <= stop_loss_threshold:
                     decision = TradeDecision(
@@ -406,6 +508,22 @@ async def trading_cycle(
                         loss_pct,
                         stop_loss_threshold,
                     )
+                elif loss_pct >= take_profit_threshold:
+                    decision = TradeDecision(
+                        action="SELL",
+                        confidence=90,
+                        rationale=(
+                            f"Take-profit triggered ({loss_pct:.2f}% >= "
+                            f"{take_profit_threshold:.2f}%)"
+                        ),
+                    )
+                    logger.info(
+                        "Take-profit override for %s (%s): %.2f%% >= %.2f%%",
+                        stock_code,
+                        market.name,
+                        loss_pct,
+                        take_profit_threshold,
+                    )
     logger.info(
         "Decision for %s (%s): %s (confidence=%d)",
         stock_code,
@@ -466,12 +584,23 @@ async def trading_cycle(
     trade_price = current_price
     trade_pnl = 0.0
     if decision.action in ("BUY", "SELL"):
+        broker_held_qty = (
+            _extract_held_qty_from_balance(
+                balance_data, stock_code, is_domestic=market.is_domestic
+            )
+            if decision.action == "SELL"
+            else 0
+        )
+        matched_scenario = match.matched_scenario
         quantity = _determine_order_quantity(
             action=decision.action,
             current_price=current_price,
             total_cash=total_cash,
             candidate=candidate,
             settings=settings,
+            broker_held_qty=broker_held_qty,
+            playbook_allocation_pct=matched_scenario.allocation_pct if matched_scenario else None,
+            scenario_confidence=match.confidence,
         )
         if quantity <= 0:
             logger.info(
@@ -891,12 +1020,20 @@ async def run_daily_session(
             trade_pnl = 0.0
             order_succeeded = True
             if decision.action in ("BUY", "SELL"):
+                daily_broker_held_qty = (
+                    _extract_held_qty_from_balance(
+                        balance_data, stock_code, is_domestic=market.is_domestic
+                    )
+                    if decision.action == "SELL"
+                    else 0
+                )
                 quantity = _determine_order_quantity(
                     action=decision.action,
                     current_price=stock_data["current_price"],
                     total_cash=total_cash,
                     candidate=candidate_map.get(stock_code),
                     settings=settings,
+                    broker_held_qty=daily_broker_held_qty,
                 )
                 if quantity <= 0:
                     logger.info(
@@ -1208,6 +1345,15 @@ async def run(settings: Settings) -> None:
         bot_token=settings.TELEGRAM_BOT_TOKEN,
         chat_id=settings.TELEGRAM_CHAT_ID,
         enabled=settings.TELEGRAM_ENABLED,
+        notification_filter=NotificationFilter(
+            trades=settings.TELEGRAM_NOTIFY_TRADES,
+            market_open_close=settings.TELEGRAM_NOTIFY_MARKET_OPEN_CLOSE,
+            fat_finger=settings.TELEGRAM_NOTIFY_FAT_FINGER,
+            system_events=settings.TELEGRAM_NOTIFY_SYSTEM_EVENTS,
+            playbook=settings.TELEGRAM_NOTIFY_PLAYBOOK,
+            scenario_match=settings.TELEGRAM_NOTIFY_SCENARIO_MATCH,
+            errors=settings.TELEGRAM_NOTIFY_ERRORS,
+        ),
     )
 
     # Initialize Telegram command handler
@@ -1226,7 +1372,11 @@ async def run(settings: Settings) -> None:
             "/review - Recent scorecards\n"
             "/dashboard - Dashboard URL/status\n"
             "/stop - Pause trading\n"
-            "/resume - Resume trading"
+            "/resume - Resume trading\n"
+            "/notify - Show notification filter status\n"
+            "/notify [key] [on|off] - Toggle notification type\n"
+            "  Keys: trades, market, scenario, playbook,\n"
+            "        system, fatfinger, errors, all"
         )
         await telegram.send_message(message)
 
@@ -1479,6 +1629,63 @@ async def run(settings: Settings) -> None:
                 "<b>⚠️ Error</b>\n\nFailed to retrieve reviews."
             )
 
+    async def handle_notify(args: list[str]) -> None:
+        """Handle /notify [key] [on|off] — query or change notification filters."""
+        status = telegram.filter_status()
+
+        # /notify — show current state
+        if not args:
+            lines = ["<b>🔔 알림 필터 현재 상태</b>\n"]
+            for key, enabled in status.items():
+                icon = "✅" if enabled else "❌"
+                lines.append(f"{icon} <code>{key}</code>")
+            lines.append("\n<i>예) /notify scenario off</i>")
+            lines.append("<i>예) /notify all off</i>")
+            await telegram.send_message("\n".join(lines))
+            return
+
+        # /notify [key] — missing on/off
+        if len(args) == 1:
+            key = args[0].lower()
+            if key == "all":
+                lines = ["<b>🔔 알림 필터 현재 상태</b>\n"]
+                for k, enabled in status.items():
+                    icon = "✅" if enabled else "❌"
+                    lines.append(f"{icon} <code>{k}</code>")
+                await telegram.send_message("\n".join(lines))
+            elif key in status:
+                icon = "✅" if status[key] else "❌"
+                await telegram.send_message(
+                    f"<b>🔔 {key}</b>: {icon} {'켜짐' if status[key] else '꺼짐'}\n"
+                    f"<i>/notify {key} on  또는  /notify {key} off</i>"
+                )
+            else:
+                valid = ", ".join(list(status.keys()) + ["all"])
+                await telegram.send_message(
+                    f"❌ 알 수 없는 키: <code>{key}</code>\n"
+                    f"유효한 키: {valid}"
+                )
+            return
+
+        # /notify [key] [on|off]
+        key, toggle = args[0].lower(), args[1].lower()
+        if toggle not in ("on", "off"):
+            await telegram.send_message("❌ on 또는 off 를 입력해 주세요.")
+            return
+        value = toggle == "on"
+        if telegram.set_notification(key, value):
+            icon = "✅" if value else "❌"
+            label = f"전체 알림" if key == "all" else f"<code>{key}</code> 알림"
+            state = "켜짐" if value else "꺼짐"
+            await telegram.send_message(f"{icon} {label} → {state}")
+            logger.info("Notification filter changed via Telegram: %s=%s", key, value)
+        else:
+            valid = ", ".join(list(telegram.filter_status().keys()) + ["all"])
+            await telegram.send_message(
+                f"❌ 알 수 없는 키: <code>{key}</code>\n"
+                f"유효한 키: {valid}"
+            )
+
     async def handle_dashboard() -> None:
         """Handle /dashboard command - show dashboard URL if enabled."""
         if not settings.DASHBOARD_ENABLED:
@@ -1502,6 +1709,7 @@ async def run(settings: Settings) -> None:
     command_handler.register_command("scenarios", handle_scenarios)
     command_handler.register_command("review", handle_review)
     command_handler.register_command("dashboard", handle_dashboard)
+    command_handler.register_command_with_args("notify", handle_notify)
 
     # Initialize volatility hunter
     volatility_analyzer = VolatilityAnalyzer(min_volume_surge=2.0, min_price_change=1.0)
@@ -1792,8 +2000,38 @@ async def run(settings: Settings) -> None:
                         except Exception as exc:
                             logger.error("Smart Scanner failed for %s: %s", market.name, exc)
 
-                    # Get active stocks from scanner (dynamic, no static fallback)
+                    # Get active stocks from scanner (dynamic, no static fallback).
-                    stock_codes = active_stocks.get(market.code, [])
+                    # Also include currently-held positions so stop-loss /
+                    # take-profit can fire even when a holding drops off the
+                    # scanner.  Broker balance is the source of truth here —
+                    # unlike the local DB it reflects actual fills and any
+                    # manual trades done outside the bot.
+                    scanner_codes = active_stocks.get(market.code, [])
+                    try:
+                        if market.is_domestic:
+                            held_balance = await broker.get_balance()
+                        else:
+                            held_balance = await overseas_broker.get_overseas_balance(
+                                market.exchange_code
+                            )
+                        held_codes = _extract_held_codes_from_balance(
+                            held_balance, is_domestic=market.is_domestic
+                        )
+                    except Exception as exc:
+                        logger.warning(
+                            "Failed to fetch holdings for %s: %s — skipping holdings merge",
+                            market.name, exc,
+                        )
+                        held_codes = []
+
+                    stock_codes = list(dict.fromkeys(scanner_codes + held_codes))
+                    extra_held = [c for c in held_codes if c not in set(scanner_codes)]
+                    if extra_held:
+                        logger.info(
+                            "Holdings added to loop for %s (not in scanner): %s",
+                            market.name, extra_held,
+                        )
+
                     if not stock_codes:
                         logger.debug("No active stocks for market %s", market.code)
                         continue

src/notifications/telegram_client.py

@@ -4,8 +4,9 @@ import asyncio
 import logging
 import time
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, fields
 from enum import Enum
+from typing import ClassVar
 
 import aiohttp
 
@@ -58,6 +59,45 @@ class LeakyBucket:
                 self._tokens -= 1.0
 
 
+@dataclass
+class NotificationFilter:
+    """Granular on/off flags for each notification type.
+
+    circuit_breaker is intentionally omitted — it is always sent regardless.
+    """
+
+    # Maps user-facing command keys to dataclass field names
+    KEYS: ClassVar[dict[str, str]] = {
+        "trades": "trades",
+        "market": "market_open_close",
+        "fatfinger": "fat_finger",
+        "system": "system_events",
+        "playbook": "playbook",
+        "scenario": "scenario_match",
+        "errors": "errors",
+    }
+
+    trades: bool = True
+    market_open_close: bool = True
+    fat_finger: bool = True
+    system_events: bool = True
+    playbook: bool = True
+    scenario_match: bool = True
+    errors: bool = True
+
+    def set_flag(self, key: str, value: bool) -> bool:
+        """Set a filter flag by user-facing key. Returns False if key is unknown."""
+        field = self.KEYS.get(key.lower())
+        if field is None:
+            return False
+        setattr(self, field, value)
+        return True
+
+    def as_dict(self) -> dict[str, bool]:
+        """Return {user_key: current_value} for display."""
+        return {k: getattr(self, field) for k, field in self.KEYS.items()}
+
+
 @dataclass
 class NotificationMessage:
     """Internal notification message structure."""
@@ -79,6 +119,7 @@ class TelegramClient:
         chat_id: str | None = None,
         enabled: bool = True,
         rate_limit: float = DEFAULT_RATE,
+        notification_filter: NotificationFilter | None = None,
     ) -> None:
         """
         Initialize Telegram client.
@@ -88,12 +129,14 @@ class TelegramClient:
             chat_id: Target chat ID (user or group)
             enabled: Enable/disable notifications globally
             rate_limit: Maximum messages per second
+            notification_filter: Granular per-type on/off flags
         """
         self._bot_token = bot_token
         self._chat_id = chat_id
         self._enabled = enabled
         self._rate_limiter = LeakyBucket(rate=rate_limit)
         self._session: aiohttp.ClientSession | None = None
+        self._filter = notification_filter if notification_filter is not None else NotificationFilter()
 
         if not enabled:
             logger.info("Telegram notifications disabled via configuration")
@@ -118,6 +161,26 @@ class TelegramClient:
         if self._session is not None and not self._session.closed:
             await self._session.close()
 
+    def set_notification(self, key: str, value: bool) -> bool:
+        """Toggle a notification type by user-facing key at runtime.
+
+        Args:
+            key: User-facing key (e.g. "scenario", "market", "all")
+            value: True to enable, False to disable
+
+        Returns:
+            True if key was valid, False if unknown.
+        """
+        if key == "all":
+            for k in NotificationFilter.KEYS:
+                self._filter.set_flag(k, value)
+            return True
+        return self._filter.set_flag(key, value)
+
+    def filter_status(self) -> dict[str, bool]:
+        """Return current per-type filter state keyed by user-facing names."""
+        return self._filter.as_dict()
+
     async def send_message(self, text: str, parse_mode: str = "HTML") -> bool:
         """
         Send a generic text message to Telegram.
@@ -193,6 +256,8 @@ class TelegramClient:
             price: Execution price
             confidence: AI confidence level (0-100)
         """
+        if not self._filter.trades:
+            return
         emoji = "🟢" if action == "BUY" else "🔴"
         message = (
             f"<b>{emoji} {action}</b>\n"
@@ -212,6 +277,8 @@ class TelegramClient:
         Args:
             market_name: Name of the market (e.g., "Korea", "United States")
         """
+        if not self._filter.market_open_close:
+            return
         message = f"<b>Market Open</b>\n{market_name} trading session started"
         await self._send_notification(
             NotificationMessage(priority=NotificationPriority.LOW, message=message)
@@ -225,6 +292,8 @@ class TelegramClient:
             market_name: Name of the market
             pnl_pct: Final P&L percentage for the session
         """
+        if not self._filter.market_open_close:
+            return
         pnl_sign = "+" if pnl_pct >= 0 else ""
         pnl_emoji = "📈" if pnl_pct >= 0 else "📉"
         message = (
@@ -271,6 +340,8 @@ class TelegramClient:
             total_cash: Total available cash
             max_pct: Maximum allowed percentage
         """
+        if not self._filter.fat_finger:
+            return
         attempted_pct = (order_amount / total_cash) * 100 if total_cash > 0 else 0
         message = (
             f"<b>Fat-Finger Protection</b>\n"
@@ -293,6 +364,8 @@ class TelegramClient:
             mode: Trading mode ("paper" or "live")
             enabled_markets: List of enabled market codes
         """
+        if not self._filter.system_events:
+            return
         mode_emoji = "📝" if mode == "paper" else "💰"
         markets_str = ", ".join(enabled_markets)
         message = (
@@ -320,6 +393,8 @@ class TelegramClient:
             scenario_count: Total number of scenarios
             token_count: Gemini token usage for the playbook
         """
+        if not self._filter.playbook:
+            return
         message = (
             f"<b>Playbook Generated</b>\n"
             f"Market: {market}\n"
@@ -347,6 +422,8 @@ class TelegramClient:
             condition_summary: Short summary of the matched condition
             confidence: Scenario confidence (0-100)
         """
+        if not self._filter.scenario_match:
+            return
         message = (
             f"<b>Scenario Matched</b>\n"
             f"Symbol: <code>{stock_code}</code>\n"
@@ -366,6 +443,8 @@ class TelegramClient:
             market: Market code (e.g., "KR", "US")
             reason: Failure reason summary
         """
+        if not self._filter.playbook:
+            return
         message = (
             f"<b>Playbook Failed</b>\n"
             f"Market: {market}\n"
@@ -382,6 +461,8 @@ class TelegramClient:
         Args:
             reason: Reason for shutdown (e.g., "Normal shutdown", "Circuit breaker")
         """
+        if not self._filter.system_events:
+            return
         message = f"<b>System Shutdown</b>\n{reason}"
         priority = (
             NotificationPriority.CRITICAL
@@ -403,6 +484,8 @@ class TelegramClient:
             error_msg: Error message
             context: Error context (e.g., stock code, market)
         """
+        if not self._filter.errors:
+            return
         message = (
             f"<b>Error: {error_type}</b>\n"
             f"Context: {context}\n"
@@ -429,6 +512,7 @@ class TelegramCommandHandler:
         self._client = client
         self._polling_interval = polling_interval
         self._commands: dict[str, Callable[[], Awaitable[None]]] = {}
+        self._commands_with_args: dict[str, Callable[[list[str]], Awaitable[None]]] = {}
         self._last_update_id = 0
         self._polling_task: asyncio.Task[None] | None = None
         self._running = False
@@ -437,7 +521,7 @@ class TelegramCommandHandler:
         self, command: str, handler: Callable[[], Awaitable[None]]
     ) -> None:
         """
-        Register a command handler.
+        Register a command handler (no arguments).
 
         Args:
             command: Command name (without leading slash, e.g., "start")
@@ -446,6 +530,19 @@ class TelegramCommandHandler:
         self._commands[command] = handler
         logger.debug("Registered command handler: /%s", command)
 
+    def register_command_with_args(
+        self, command: str, handler: Callable[[list[str]], Awaitable[None]]
+    ) -> None:
+        """
+        Register a command handler that receives trailing arguments.
+
+        Args:
+            command: Command name (without leading slash, e.g., "notify")
+            handler: Async function receiving list of argument tokens
+        """
+        self._commands_with_args[command] = handler
+        logger.debug("Registered command handler (with args): /%s", command)
+
     async def start_polling(self) -> None:
         """Start long polling for commands."""
         if self._running:
@@ -566,11 +663,14 @@ class TelegramCommandHandler:
             # Remove @botname suffix if present (for group chats)
             command_name = command_parts[0].split("@")[0]
 
-            # Execute handler
+            # Execute handler (args-aware handlers take priority)
-            handler = self._commands.get(command_name)
+            args_handler = self._commands_with_args.get(command_name)
-            if handler:
+            if args_handler:
+                logger.info("Executing command: /%s %s", command_name, command_parts[1:])
+                await args_handler(command_parts[1:])
+            elif command_name in self._commands:
                 logger.info("Executing command: /%s", command_name)
-                await handler()
+                await self._commands[command_name]()
             else:
                 logger.debug("Unknown command: /%s", command_name)
                 await self._client.send_message(

tests/test_main.py

@@ -14,6 +14,9 @@ from src.evolution.scorecard import DailyScorecard
 from src.logging.decision_logger import DecisionLogger
 from src.main import (
     _apply_dashboard_flag,
+    _determine_order_quantity,
+    _extract_held_codes_from_balance,
+    _extract_held_qty_from_balance,
     _handle_market_close,
     _run_context_scheduler,
     _run_evolution_loop,
@@ -68,6 +71,219 @@ def _make_sell_match(stock_code: str = "005930") -> ScenarioMatch:
     )
 
 
+class TestExtractHeldQtyFromBalance:
+    """Tests for _extract_held_qty_from_balance()."""
+
+    def _domestic_balance(self, stock_code: str, ord_psbl_qty: int) -> dict:
+        return {
+            "output1": [{"pdno": stock_code, "ord_psbl_qty": str(ord_psbl_qty)}],
+            "output2": [{"dnca_tot_amt": "1000000"}],
+        }
+
+    def test_domestic_returns_ord_psbl_qty(self) -> None:
+        balance = self._domestic_balance("005930", 7)
+        assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 7
+
+    def test_domestic_fallback_to_hldg_qty(self) -> None:
+        balance = {"output1": [{"pdno": "005930", "hldg_qty": "3"}]}
+        assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 3
+
+    def test_domestic_returns_zero_when_not_found(self) -> None:
+        balance = self._domestic_balance("005930", 5)
+        assert _extract_held_qty_from_balance(balance, "000660", is_domestic=True) == 0
+
+    def test_domestic_returns_zero_when_output1_empty(self) -> None:
+        balance = {"output1": [], "output2": [{}]}
+        assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 0
+
+    def test_overseas_returns_ovrs_cblc_qty(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_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
+
+    def test_case_insensitive_match(self) -> None:
+        balance = {"output1": [{"pdno": "005930", "ord_psbl_qty": "2"}]}
+        assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 2
+
+
+class TestExtractHeldCodesFromBalance:
+    """Tests for _extract_held_codes_from_balance()."""
+
+    def test_returns_codes_with_positive_qty(self) -> None:
+        balance = {
+            "output1": [
+                {"pdno": "005930", "ord_psbl_qty": "5"},
+                {"pdno": "000660", "ord_psbl_qty": "3"},
+            ]
+        }
+        result = _extract_held_codes_from_balance(balance, is_domestic=True)
+        assert set(result) == {"005930", "000660"}
+
+    def test_excludes_zero_qty_holdings(self) -> None:
+        balance = {
+            "output1": [
+                {"pdno": "005930", "ord_psbl_qty": "0"},
+                {"pdno": "000660", "ord_psbl_qty": "2"},
+            ]
+        }
+        result = _extract_held_codes_from_balance(balance, is_domestic=True)
+        assert "005930" not in result
+        assert "000660" in result
+
+    def test_returns_empty_when_output1_missing(self) -> None:
+        balance: dict = {}
+        assert _extract_held_codes_from_balance(balance, is_domestic=True) == []
+
+    def test_overseas_uses_ovrs_pdno(self) -> None:
+        balance = {"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "3"}]}
+        result = _extract_held_codes_from_balance(balance, is_domestic=False)
+        assert result == ["AAPL"]
+
+
+class TestDetermineOrderQuantity:
+    """Test _determine_order_quantity() — SELL uses broker_held_qty."""
+
+    def test_sell_returns_broker_held_qty(self) -> None:
+        result = _determine_order_quantity(
+            action="SELL",
+            current_price=105.0,
+            total_cash=50000.0,
+            candidate=None,
+            settings=None,
+            broker_held_qty=7,
+        )
+        assert result == 7
+
+    def test_sell_returns_zero_when_broker_qty_zero(self) -> None:
+        result = _determine_order_quantity(
+            action="SELL",
+            current_price=105.0,
+            total_cash=50000.0,
+            candidate=None,
+            settings=None,
+            broker_held_qty=0,
+        )
+        assert result == 0
+
+    def test_buy_without_position_sizing_returns_one(self) -> None:
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=None,
+        )
+        assert result == 1
+
+    def test_buy_with_zero_cash_returns_zero(self) -> None:
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=0.0,
+            candidate=None,
+            settings=None,
+        )
+        assert result == 0
+
+    def test_buy_with_position_sizing_calculates_correctly(self) -> None:
+        settings = MagicMock(spec=Settings)
+        settings.POSITION_SIZING_ENABLED = True
+        settings.POSITION_VOLATILITY_TARGET_SCORE = 50.0
+        settings.POSITION_BASE_ALLOCATION_PCT = 10.0
+        settings.POSITION_MAX_ALLOCATION_PCT = 30.0
+        settings.POSITION_MIN_ALLOCATION_PCT = 1.0
+        # 1,000,000 * 10% = 100,000 budget // 50,000 price = 2 shares
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=settings,
+        )
+        assert result == 2
+
+    def test_determine_order_quantity_uses_playbook_allocation_pct(self) -> None:
+        """playbook_allocation_pct should take priority over volatility-based sizing."""
+        settings = MagicMock(spec=Settings)
+        settings.POSITION_SIZING_ENABLED = True
+        settings.POSITION_MAX_ALLOCATION_PCT = 30.0
+        settings.POSITION_MIN_ALLOCATION_PCT = 1.0
+        # playbook says 20%, confidence 80 → scale=1.0 → 20%
+        # 1,000,000 * 20% = 200,000 // 50,000 price = 4 shares
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=settings,
+            playbook_allocation_pct=20.0,
+            scenario_confidence=80,
+        )
+        assert result == 4
+
+    def test_determine_order_quantity_confidence_scales_allocation(self) -> None:
+        """Higher confidence should produce a larger allocation (up to max)."""
+        settings = MagicMock(spec=Settings)
+        settings.POSITION_SIZING_ENABLED = True
+        settings.POSITION_MAX_ALLOCATION_PCT = 30.0
+        settings.POSITION_MIN_ALLOCATION_PCT = 1.0
+        # confidence 96 → scale=1.2 → 10% * 1.2 = 12%
+        # 1,000,000 * 12% = 120,000 // 50,000 price = 2 shares
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=settings,
+            playbook_allocation_pct=10.0,
+            scenario_confidence=96,
+        )
+        # scale = 96/80 = 1.2 → effective_pct = 12.0
+        # budget = 1_000_000 * 0.12 = 120_000 → qty = 120_000 // 50_000 = 2
+        assert result == 2
+
+    def test_determine_order_quantity_confidence_clamped_to_max(self) -> None:
+        """Confidence scaling should not exceed POSITION_MAX_ALLOCATION_PCT."""
+        settings = MagicMock(spec=Settings)
+        settings.POSITION_SIZING_ENABLED = True
+        settings.POSITION_MAX_ALLOCATION_PCT = 15.0
+        settings.POSITION_MIN_ALLOCATION_PCT = 1.0
+        # playbook 20% * scale 1.5 = 30% → clamped to 15%
+        # 1,000,000 * 15% = 150,000 // 50,000 price = 3 shares
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=settings,
+            playbook_allocation_pct=20.0,
+            scenario_confidence=120,  # extreme → scale = 1.5
+        )
+        assert result == 3
+
+    def test_determine_order_quantity_fallback_when_no_playbook(self) -> None:
+        """Without playbook_allocation_pct, falls back to volatility-based sizing."""
+        settings = MagicMock(spec=Settings)
+        settings.POSITION_SIZING_ENABLED = True
+        settings.POSITION_VOLATILITY_TARGET_SCORE = 50.0
+        settings.POSITION_BASE_ALLOCATION_PCT = 10.0
+        settings.POSITION_MAX_ALLOCATION_PCT = 30.0
+        settings.POSITION_MIN_ALLOCATION_PCT = 1.0
+        # Same as test_buy_with_position_sizing_calculates_correctly (no playbook)
+        result = _determine_order_quantity(
+            action="BUY",
+            current_price=50000.0,
+            total_cash=1000000.0,
+            candidate=None,
+            settings=settings,
+            playbook_allocation_pct=None,  # explicit None → fallback
+        )
+        assert result == 2
+
+
 class TestSafeFloat:
     """Test safe_float() helper function."""
 
@@ -1240,13 +1456,14 @@ async def test_sell_updates_original_buy_decision_outcome() -> None:
     broker.get_current_price = AsyncMock(return_value=(120.0, 0.0, 0.0))
     broker.get_balance = AsyncMock(
         return_value={
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "1"}],
             "output2": [
                 {
                     "tot_evlu_amt": "100000",
                     "dnca_tot_amt": "10000",
                     "pchs_amt_smtl_amt": "90000",
                 }
-            ]
+            ],
         }
     )
     broker.send_order = AsyncMock(return_value={"msg1": "OK"})
@@ -1330,13 +1547,14 @@ async def test_hold_overridden_to_sell_when_stop_loss_triggered() -> None:
     broker.get_current_price = AsyncMock(return_value=(95.0, -5.0, 0.0))
     broker.get_balance = AsyncMock(
         return_value={
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "1"}],
             "output2": [
                 {
                     "tot_evlu_amt": "100000",
                     "dnca_tot_amt": "10000",
                     "pchs_amt_smtl_amt": "90000",
                 }
-            ]
+            ],
         }
     )
     broker.send_order = AsyncMock(return_value={"msg1": "OK"})
@@ -1396,6 +1614,318 @@ async def test_hold_overridden_to_sell_when_stop_loss_triggered() -> None:
     assert broker.send_order.call_args.kwargs["order_type"] == "SELL"
 
 
+@pytest.mark.asyncio
+async def test_hold_overridden_to_sell_when_take_profit_triggered() -> None:
+    """HOLD decision should be overridden to SELL when take-profit threshold is reached."""
+    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,
+        market="KR",
+        exchange_code="KRX",
+        decision_id=buy_decision_id,
+    )
+
+    broker = MagicMock()
+    # Current price 106.0 → +6% gain, above take_profit_pct=3.0
+    broker.get_current_price = AsyncMock(return_value=(106.0, 6.0, 0.0))
+    broker.get_balance = AsyncMock(
+        return_value={
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "1"}],
+            "output2": [
+                {
+                    "tot_evlu_amt": "100000",
+                    "dnca_tot_amt": "10000",
+                    "pchs_amt_smtl_amt": "90000",
+                }
+            ],
+        }
+    )
+    broker.send_order = AsyncMock(return_value={"msg1": "OK"})
+
+    scenario = StockScenario(
+        condition=StockCondition(rsi_below=30),
+        action=ScenarioAction.BUY,
+        confidence=88,
+        stop_loss_pct=-2.0,
+        take_profit_pct=3.0,
+        rationale="take profit policy",
+    )
+    playbook = DayPlaybook(
+        date=date(2026, 2, 8),
+        market="KR",
+        stock_playbooks=[
+            {"stock_code": "005930", "stock_name": "Samsung", "scenarios": [scenario]}
+        ],
+    )
+    engine = MagicMock(spec=ScenarioEngine)
+    engine.evaluate = MagicMock(return_value=_make_hold_match())
+
+    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=engine,
+        playbook=playbook,
+        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={},
+    )
+
+    broker.send_order.assert_called_once()
+    assert broker.send_order.call_args.kwargs["order_type"] == "SELL"
+
+
+@pytest.mark.asyncio
+async def test_hold_not_overridden_when_between_stop_loss_and_take_profit() -> None:
+    """HOLD should remain HOLD when P&L is within stop-loss and take-profit bounds."""
+    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,
+        market="KR",
+        exchange_code="KRX",
+        decision_id=buy_decision_id,
+    )
+
+    broker = MagicMock()
+    # Current price 101.0 → +1% gain, within [-2%, +3%] range
+    broker.get_current_price = AsyncMock(return_value=(101.0, 1.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"})
+
+    scenario = StockScenario(
+        condition=StockCondition(rsi_below=30),
+        action=ScenarioAction.BUY,
+        confidence=88,
+        stop_loss_pct=-2.0,
+        take_profit_pct=3.0,
+        rationale="within range policy",
+    )
+    playbook = DayPlaybook(
+        date=date(2026, 2, 8),
+        market="KR",
+        stock_playbooks=[
+            {"stock_code": "005930", "stock_name": "Samsung", "scenarios": [scenario]}
+        ],
+    )
+    engine = MagicMock(spec=ScenarioEngine)
+    engine.evaluate = MagicMock(return_value=_make_hold_match())
+
+    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=engine,
+        playbook=playbook,
+        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={},
+    )
+
+    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.
+
+    The DB records order quantity which may differ from actual fill quantity.
+    This test verifies that we use the broker-confirmed orderable quantity.
+    """
+    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={},
+    )
+    # DB records 10 shares ordered — but only 5 actually filled (partial fill scenario)
+    log_trade(
+        conn=db_conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=90,
+        rationale="entry",
+        quantity=10,  # ordered quantity (may differ from fill)
+        price=100.0,
+        market="KR",
+        exchange_code="KRX",
+        decision_id=buy_decision_id,
+    )
+
+    broker = MagicMock()
+    # Stop-loss triggers (price dropped below -2%)
+    broker.get_current_price = AsyncMock(return_value=(95.0, -5.0, 0.0))
+    broker.get_balance = AsyncMock(
+        return_value={
+            # Broker confirms only 5 shares are actually orderable (partial fill)
+            "output1": [{"pdno": "005930", "ord_psbl_qty": "5"}],
+            "output2": [
+                {
+                    "tot_evlu_amt": "100000",
+                    "dnca_tot_amt": "10000",
+                    "pchs_amt_smtl_amt": "90000",
+                }
+            ],
+        }
+    )
+    broker.send_order = AsyncMock(return_value={"msg1": "OK"})
+
+    scenario = StockScenario(
+        condition=StockCondition(rsi_below=30),
+        action=ScenarioAction.BUY,
+        confidence=88,
+        stop_loss_pct=-2.0,
+        rationale="stop loss policy",
+    )
+    playbook = DayPlaybook(
+        date=date(2026, 2, 8),
+        market="KR",
+        stock_playbooks=[
+            {"stock_code": "005930", "stock_name": "Samsung", "scenarios": [scenario]}
+        ],
+    )
+    engine = MagicMock(spec=ScenarioEngine)
+    engine.evaluate = MagicMock(return_value=_make_hold_match())
+
+    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=engine,
+        playbook=playbook,
+        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={},
+    )
+
+    broker.send_order.assert_called_once()
+    call_kwargs = broker.send_order.call_args.kwargs
+    assert call_kwargs["order_type"] == "SELL"
+    # Must use broker-confirmed qty (5), NOT DB-recorded ordered qty (10)
+    assert call_kwargs["quantity"] == 5
+
+
 @pytest.mark.asyncio
 async def test_handle_market_close_runs_daily_review_flow() -> None:
     """Market close should aggregate, create scorecard, lessons, and notify."""

tests/test_telegram.py

@@ -5,7 +5,7 @@ from unittest.mock import AsyncMock, patch
 import aiohttp
 import pytest
 
-from src.notifications.telegram_client import NotificationPriority, TelegramClient
+from src.notifications.telegram_client import NotificationFilter, NotificationPriority, TelegramClient
 
 
 class TestTelegramClientInit:
@@ -481,3 +481,187 @@ class TestClientCleanup:
 
         # Should not raise exception
         await client.close()
+
+
+class TestNotificationFilter:
+    """Test granular notification filter behavior."""
+
+    def test_default_filter_allows_all(self) -> None:
+        """Default NotificationFilter has all flags enabled."""
+        f = NotificationFilter()
+        assert f.trades is True
+        assert f.market_open_close is True
+        assert f.fat_finger is True
+        assert f.system_events is True
+        assert f.playbook is True
+        assert f.scenario_match is True
+        assert f.errors is True
+
+    def test_client_uses_default_filter_when_none_given(self) -> None:
+        """TelegramClient creates a default NotificationFilter when none provided."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        assert isinstance(client._filter, NotificationFilter)
+        assert client._filter.scenario_match is True
+
+    def test_client_stores_provided_filter(self) -> None:
+        """TelegramClient stores a custom NotificationFilter."""
+        nf = NotificationFilter(scenario_match=False, trades=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        assert client._filter.scenario_match is False
+        assert client._filter.trades is False
+        assert client._filter.market_open_close is True  # default still True
+
+    @pytest.mark.asyncio
+    async def test_scenario_match_filtered_does_not_send(self) -> None:
+        """notify_scenario_matched skips send when scenario_match=False."""
+        nf = NotificationFilter(scenario_match=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_scenario_matched(
+                stock_code="005930", action="BUY", condition_summary="rsi<30", confidence=85.0
+            )
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_trades_filtered_does_not_send(self) -> None:
+        """notify_trade_execution skips send when trades=False."""
+        nf = NotificationFilter(trades=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_trade_execution(
+                stock_code="005930", market="KR", action="BUY",
+                quantity=10, price=70000.0, confidence=85.0
+            )
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_market_open_close_filtered_does_not_send(self) -> None:
+        """notify_market_open/close skip send when market_open_close=False."""
+        nf = NotificationFilter(market_open_close=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_market_open("Korea")
+            await client.notify_market_close("Korea", pnl_pct=1.5)
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_circuit_breaker_always_sends_regardless_of_filter(self) -> None:
+        """notify_circuit_breaker always sends (no filter flag)."""
+        nf = NotificationFilter(
+            trades=False, market_open_close=False, fat_finger=False,
+            system_events=False, playbook=False, scenario_match=False, errors=False,
+        )
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        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:
+            await client.notify_circuit_breaker(pnl_pct=-3.5, threshold=-3.0)
+            assert mock_post.call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_errors_filtered_does_not_send(self) -> None:
+        """notify_error skips send when errors=False."""
+        nf = NotificationFilter(errors=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_error("TestError", "something went wrong", "KR")
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_playbook_filtered_does_not_send(self) -> None:
+        """notify_playbook_generated/failed skip send when playbook=False."""
+        nf = NotificationFilter(playbook=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_playbook_generated("KR", 3, 10, 1200)
+            await client.notify_playbook_failed("KR", "timeout")
+            mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_system_events_filtered_does_not_send(self) -> None:
+        """notify_system_start/shutdown skip send when system_events=False."""
+        nf = NotificationFilter(system_events=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        with patch("aiohttp.ClientSession.post") as mock_post:
+            await client.notify_system_start("paper", ["KR"])
+            await client.notify_system_shutdown("Normal shutdown")
+            mock_post.assert_not_called()
+
+    def test_set_flag_valid_key(self) -> None:
+        """set_flag returns True and updates field for a known key."""
+        nf = NotificationFilter()
+        assert nf.set_flag("scenario", False) is True
+        assert nf.scenario_match is False
+
+    def test_set_flag_invalid_key(self) -> None:
+        """set_flag returns False for an unknown key."""
+        nf = NotificationFilter()
+        assert nf.set_flag("unknown_key", False) is False
+
+    def test_as_dict_keys_match_KEYS(self) -> None:
+        """as_dict() returns every key defined in KEYS."""
+        nf = NotificationFilter()
+        d = nf.as_dict()
+        assert set(d.keys()) == set(NotificationFilter.KEYS.keys())
+
+    def test_set_notification_valid_key(self) -> None:
+        """TelegramClient.set_notification toggles filter at runtime."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        assert client._filter.scenario_match is True
+        assert client.set_notification("scenario", False) is True
+        assert client._filter.scenario_match is False
+
+    def test_set_notification_all_off(self) -> None:
+        """set_notification('all', False) disables every filter flag."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        assert client.set_notification("all", False) is True
+        for v in client.filter_status().values():
+            assert v is False
+
+    def test_set_notification_all_on(self) -> None:
+        """set_notification('all', True) enables every filter flag."""
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True,
+            notification_filter=NotificationFilter(
+                trades=False, market_open_close=False, scenario_match=False,
+                fat_finger=False, system_events=False, playbook=False, errors=False,
+            ),
+        )
+        assert client.set_notification("all", True) is True
+        for v in client.filter_status().values():
+            assert v is True
+
+    def test_set_notification_unknown_key(self) -> None:
+        """set_notification returns False for an unknown key."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        assert client.set_notification("unknown", False) is False
+
+    def test_filter_status_reflects_current_state(self) -> None:
+        """filter_status() matches the current NotificationFilter state."""
+        nf = NotificationFilter(trades=False, scenario_match=False)
+        client = TelegramClient(
+            bot_token="123:abc", chat_id="456", enabled=True, notification_filter=nf
+        )
+        status = client.filter_status()
+        assert status["trades"] is False
+        assert status["scenario"] is False
+        assert status["market"] is True

tests/test_telegram_commands.py

@@ -875,3 +875,91 @@ class TestGetUpdates:
             updates = await handler._get_updates()
 
             assert updates == []
+
+
+class TestCommandWithArgs:
+    """Test register_command_with_args and argument dispatch."""
+
+    def test_register_command_with_args_stored(self) -> None:
+        """register_command_with_args stores handler in _commands_with_args."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        async def my_handler(args: list[str]) -> None:
+            pass
+
+        handler.register_command_with_args("notify", my_handler)
+        assert "notify" in handler._commands_with_args
+        assert handler._commands_with_args["notify"] is my_handler
+
+    @pytest.mark.asyncio
+    async def test_args_handler_receives_arguments(self) -> None:
+        """Args handler is called with the trailing tokens."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        received: list[list[str]] = []
+
+        async def capture(args: list[str]) -> None:
+            received.append(args)
+
+        handler.register_command_with_args("notify", capture)
+
+        update = {
+            "message": {
+                "chat": {"id": "456"},
+                "text": "/notify scenario off",
+            }
+        }
+        await handler._handle_update(update)
+        assert received == [["scenario", "off"]]
+
+    @pytest.mark.asyncio
+    async def test_args_handler_takes_priority_over_no_args_handler(self) -> None:
+        """When both handlers exist for same command, args handler wins."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        no_args_called = []
+        args_called = []
+
+        async def no_args_handler() -> None:
+            no_args_called.append(True)
+
+        async def args_handler(args: list[str]) -> None:
+            args_called.append(args)
+
+        handler.register_command("notify", no_args_handler)
+        handler.register_command_with_args("notify", args_handler)
+
+        update = {
+            "message": {
+                "chat": {"id": "456"},
+                "text": "/notify all off",
+            }
+        }
+        await handler._handle_update(update)
+        assert args_called == [["all", "off"]]
+        assert no_args_called == []
+
+    @pytest.mark.asyncio
+    async def test_args_handler_with_no_trailing_args(self) -> None:
+        """/notify with no args still dispatches to args handler with empty list."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        received: list[list[str]] = []
+
+        async def capture(args: list[str]) -> None:
+            received.append(args)
+
+        handler.register_command_with_args("notify", capture)
+
+        update = {
+            "message": {
+                "chat": {"id": "456"},
+                "text": "/notify",
+            }
+        }
+        await handler._handle_update(update)
+        assert received == [[]]