Add safe-haven cash substitution threshold

Author: Pigbibi

.github/workflows/sync-cloud-run-env.yml

@@ -31,6 +31,7 @@ jobs:
       IBKR_RECONCILIATION_OUTPUT_PATH: ${{ vars.IBKR_RECONCILIATION_OUTPUT_PATH }}
       IBKR_DRY_RUN_ONLY: ${{ vars.IBKR_DRY_RUN_ONLY }}
       IBKR_PAPER_LIQUIDATE_ONLY: ${{ vars.IBKR_PAPER_LIQUIDATE_ONLY }}
+      IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD: ${{ vars.IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD }}
       # Strategy-owned defaults continue to come from UsEquityStrategies; this workflow only syncs platform/runtime inputs.
       EXECUTION_REPORT_GCS_URI: ${{ vars.EXECUTION_REPORT_GCS_URI }}
       IB_GATEWAY_ZONE: ${{ vars.IB_GATEWAY_ZONE }}
@@ -324,6 +325,12 @@ jobs:
             remove_env_vars+=("IBKR_PAPER_LIQUIDATE_ONLY")
           fi
 
+          if [ -n "${IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD:-}" ]; then
+            env_pairs+=("IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD=${IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD}")
+          else
+            remove_env_vars+=("IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD")
+          fi
+
           if [ -n "${EXECUTION_REPORT_GCS_URI:-}" ]; then
             env_pairs+=("EXECUTION_REPORT_GCS_URI=${EXECUTION_REPORT_GCS_URI}")
           else

README.md

@@ -104,6 +104,7 @@ For IBKR, keep `paper` as a single account-group entry. If you later add live ac
 | `IBKR_FEATURE_SNAPSHOT_PATH` | Conditionally required | Required for snapshot-backed profiles such as `russell_1000_multi_factor_defensive`, `tech_communication_pullback_enhancement`, and `mega_cap_leader_rotation_top50_balanced`. Path to the latest feature snapshot file (`.csv`, `.json`, `.jsonl`, `.parquet`). |
 | `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` | No | Optional IBKR-side strategy plugin mount JSON. The plugin artifact controls mode; platform config must not set `mode`. |
 | `IBKR_MIN_ORDER_NOTIONAL_USD` | No | Minimum buy notional for limit buys; defaults to `50.0`. |
+| `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | No | Safe-haven target values below this USD amount are kept as cash instead of buying BOXX/BIL. Defaults to `1000.0`. |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Yes for Cloud Run | Secret Manager secret name for account-group config JSON. Recommended production source. |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | No | Local/dev JSON fallback for account-group config. Not recommended for production Cloud Run. |
 | `TELEGRAM_TOKEN` | Yes | Telegram bot token. For Cloud Run, prefer a Secret Manager reference instead of a literal env var. |
@@ -218,7 +219,7 @@ Recommended setup:
   - `STRATEGY_PROFILE` (set explicitly to one enabled profile, such as `soxl_soxx_trend_income`)
   - `ACCOUNT_GROUP` (recommended: `paper`)
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
-  - Optional: `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`
+  - Optional: `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`, `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **Repository Secrets**
@@ -340,6 +341,7 @@ IBKR 账户
 | `IBKR_FEATURE_SNAPSHOT_PATH` | 条件必填 | `russell_1000_multi_factor_defensive`、`tech_communication_pullback_enhancement`、`mega_cap_leader_rotation_top50_balanced` 等快照策略需要。指向最新特征快照文件（`.csv`、`.json`、`.jsonl`、`.parquet`）。 |
 | `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` | 否 | 可选的 IBKR 侧策略插件挂载 JSON。插件 artifact 自带模式；平台配置不要设置 `mode`。 |
 | `IBKR_MIN_ORDER_NOTIONAL_USD` | 否 | 限价买入的最小名义金额；默认 `50.0`。 |
+| `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | 否 | `BOXX`/`BIL` 等避险标的目标金额低于该 USD 门槛时保留现金，不买入。默认 `1000.0`。 |
 | `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME` | Cloud Run 建议必填 | 账号组配置 JSON 在 Secret Manager 里的密钥名。生产环境推荐使用。 |
 | `IB_ACCOUNT_GROUP_CONFIG_JSON` | 否 | 本地开发用的账号组配置 JSON fallback。不建议在生产 Cloud Run 直接使用。 |
 | `TELEGRAM_TOKEN` | 是 | Telegram 机器人 Token。Cloud Run 上更推荐走 Secret Manager 引用，不要直接写成明文 env。 |
@@ -420,7 +422,7 @@ IB_GATEWAY_IP_MODE=internal
   - `STRATEGY_PROFILE`（显式设置为任一已启用 profile，例如 `soxl_soxx_trend_income`）
   - `ACCOUNT_GROUP`（建议设为 `paper`）
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
-  - 可选：`IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`
+  - 可选：`IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`、`IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **仓库级 Secrets**

application/execution_service.py

@@ -510,6 +510,36 @@ def _sell_order_quantity(
     )
 
 
+DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD = 1000.0
+
+
+def _apply_safe_haven_cash_substitution_to_weights(
+    target_weights: dict[str, float],
+    *,
+    safe_haven_symbols: tuple[str, ...],
+    investable: float,
+    threshold_usd: float,
+) -> tuple[dict[str, float], tuple[str, ...]]:
+    threshold = max(0.0, float(threshold_usd or 0.0))
+    adjusted = {
+        str(symbol).strip().upper(): float(weight or 0.0)
+        for symbol, weight in dict(target_weights or {}).items()
+    }
+    if threshold <= 0.0:
+        return adjusted, ()
+
+    substituted: list[str] = []
+    for symbol in safe_haven_symbols:
+        normalized = str(symbol or "").strip().upper()
+        if not normalized:
+            continue
+        target_notional = max(0.0, float(investable or 0.0) * float(adjusted.get(normalized, 0.0) or 0.0))
+        if 0.0 < target_notional < threshold:
+            adjusted[normalized] = 0.0
+            substituted.append(normalized)
+    return adjusted, tuple(dict.fromkeys(substituted))
+
+
 def _finalize_result(trade_logs, execution_summary, *, return_summary: bool):
     if return_summary:
         return trade_logs, execution_summary
@@ -539,6 +569,7 @@ def execute_rebalance(
     sell_settle_delay_sec,
     quantity_step=1.0,
     min_order_notional=50.0,
+    safe_haven_cash_substitute_threshold_usd=DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD,
     execution_lock_dir=None,
     return_summary=False,
 ):
@@ -578,6 +609,10 @@ def execute_rebalance(
         "execution_status": "not_started",
         "no_op_reason": None,
         "cash_reserve_dollars": 0.0,
+        "safe_haven_cash_substitute_threshold_usd": float(
+            max(0.0, float(safe_haven_cash_substitute_threshold_usd or 0.0))
+        ),
+        "safe_haven_cash_substituted_symbols": [],
         "residual_cash_estimate": float(account_values.get("buying_power", 0.0) or 0.0),
         "current_stock_weight": 0.0,
         "current_safe_haven_weight": 0.0,
@@ -594,6 +629,20 @@ def execute_rebalance(
 
     reserved = equity * cash_reserve_ratio
     investable = equity - reserved
+    target_weights, substituted_safe_haven_symbols = _apply_safe_haven_cash_substitution_to_weights(
+        target_weights,
+        safe_haven_symbols=safe_haven_symbols,
+        investable=investable,
+        threshold_usd=safe_haven_cash_substitute_threshold_usd,
+    )
+    execution_summary["safe_haven_cash_substituted_symbols"] = list(substituted_safe_haven_symbols)
+    if safe_haven_symbols:
+        execution_summary["realized_safe_haven_weight"] = float(
+            sum(
+                float(target_weights.get(str(symbol or "").strip().upper(), 0.0) or 0.0)
+                for symbol in safe_haven_symbols
+            )
+        )
     threshold = equity * rebalance_threshold_ratio
     order_quantity_step = float(quantity_step or 1.0)
     minimum_order_notional = max(0.0, float(min_order_notional or 0.0))

application/runtime_broker_adapters.py

@@ -40,6 +40,7 @@ class IBKRRuntimeBrokerAdapters:
     limit_buy_premium: float
     quantity_step: float
     min_order_notional: float
+    safe_haven_cash_substitute_threshold_usd: float
     sell_settle_delay_sec: float
     separator: str
     strategy_display_name: str
@@ -160,6 +161,7 @@ def execute_rebalance(
             limit_buy_premium=self.limit_buy_premium,
             quantity_step=self.quantity_step,
             min_order_notional=self.min_order_notional,
+            safe_haven_cash_substitute_threshold_usd=self.safe_haven_cash_substitute_threshold_usd,
             sell_settle_delay_sec=self.sell_settle_delay_sec,
             return_summary=True,
         )
@@ -245,6 +247,7 @@ def build_runtime_broker_adapters(
     limit_buy_premium: float,
     quantity_step: float,
     min_order_notional: float,
+    safe_haven_cash_substitute_threshold_usd: float,
     sell_settle_delay_sec: float,
     separator: str,
     strategy_display_name: str,
@@ -280,6 +283,7 @@ def build_runtime_broker_adapters(
         limit_buy_premium=float(limit_buy_premium),
         quantity_step=float(quantity_step),
         min_order_notional=float(min_order_notional),
+        safe_haven_cash_substitute_threshold_usd=float(safe_haven_cash_substitute_threshold_usd),
         sell_settle_delay_sec=float(sell_settle_delay_sec),
         separator=str(separator or ""),
         strategy_display_name=str(strategy_display_name or ""),

main.py

@@ -327,6 +327,7 @@ def build_broker_adapters():
         limit_buy_premium=LIMIT_BUY_PREMIUM,
         quantity_step=RUNTIME_SETTINGS.quantity_step,
         min_order_notional=RUNTIME_SETTINGS.min_order_notional,
+        safe_haven_cash_substitute_threshold_usd=RUNTIME_SETTINGS.safe_haven_cash_substitute_threshold_usd,
         sell_settle_delay_sec=SELL_SETTLE_DELAY_SEC,
         separator=SEPARATOR,
         strategy_display_name=strategy_display_name,

runtime_config_support.py

@@ -24,6 +24,7 @@
 from us_equity_strategies import get_strategy_catalog
 
 DEFAULT_ACCOUNT_GROUP = "default"
+DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD = 1000.0
 
 
 @dataclass(frozen=True)
@@ -59,6 +60,7 @@ class PlatformRuntimeSettings:
     dry_run_only: bool
     quantity_step: float = 1.0
     min_order_notional: float = 50.0
+    safe_haven_cash_substitute_threshold_usd: float = DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
     account_group: str = DEFAULT_ACCOUNT_GROUP
     service_name: str | None = None
     account_ids: tuple[str, ...] = ()
@@ -151,6 +153,14 @@ def load_platform_runtime_settings(
             "IBKR_MIN_ORDER_NOTIONAL_USD",
             default=50.0,
         ),
+        safe_haven_cash_substitute_threshold_usd=max(
+            0.0,
+            resolve_float_env(
+                os.environ,
+                "IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD",
+                default=DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD,
+            ),
+        ),
         account_group=account_group,
         service_name=group_config.service_name,
         account_ids=group_config.account_ids,

scripts/print_strategy_switch_env_plan.py

@@ -67,7 +67,10 @@ def build_switch_plan(profile: str) -> dict[str, object]:
         "ACCOUNT_GROUP",
         "IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME",
     ]
-    optional_env = ["IBKR_DRY_RUN_ONLY"]
+    optional_env = [
+        "IBKR_DRY_RUN_ONLY",
+        "IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD",
+    ]
     remove_if_present: list[str] = []
     notes = [
         "Keep ACCOUNT_GROUP and IB account-group config aligned with the current service identity.",

tests/test_connect_timeout_alert.py

@@ -124,6 +124,7 @@ def run(self, *args, **kwargs):
         dry_run_only=False,
         quantity_step=1,
         min_order_notional=0.0,
+        safe_haven_cash_substitute_threshold_usd=1000.0,
         runtime_target={},
         notify_lang="en",
         tg_token=None,

tests/test_execution_service.py

@@ -470,6 +470,57 @@ def fake_fetch_quote_snapshots(_ib, symbols):
     assert summary["target_vs_current"]
 
 
+def test_execute_rebalance_keeps_small_safe_haven_target_as_cash(monkeypatch, tmp_path):
+    class FakeIB:
+        def openTrades(self):
+            return []
+
+        def fills(self):
+            return []
+
+        def accountValues(self):
+            return [SimpleNamespace(tag="AvailableFunds", currency="USD", value="1500")]
+
+    monkeypatch.setattr("application.execution_service.time.sleep", lambda _seconds: None)
+
+    trade_logs, summary = execute_rebalance(
+        FakeIB(),
+        {"VOO": 0.5, "BOXX": 0.5},
+        {},
+        {"equity": 1500.0, "buying_power": 1500.0},
+        fetch_quote_snapshots=lambda _ib, symbols: {
+            symbol: SimpleNamespace(last_price=100.0) for symbol in symbols
+        },
+        submit_order_intent=lambda *_args, **_kwargs: SimpleNamespace(broker_order_id="1", status="Submitted"),
+        order_intent_cls=OrderIntent,
+        translator=translate,
+        strategy_symbols=["VOO", "BOXX"],
+        strategy_profile="tech_communication_pullback_enhancement",
+        signal_metadata=_signal_metadata(
+            {"VOO": 0.5, "BOXX": 0.5},
+            risk_symbols=("VOO",),
+            safe_haven_symbols=("BOXX",),
+            trade_date="2026-04-01",
+            snapshot_as_of="2026-03-31",
+        ),
+        dry_run_only=True,
+        cash_reserve_ratio=0.0,
+        rebalance_threshold_ratio=0.01,
+        limit_buy_premium=1.0,
+        sell_settle_delay_sec=0,
+        execution_lock_dir=tmp_path,
+        return_summary=True,
+        safe_haven_cash_substitute_threshold_usd=1000.0,
+    )
+
+    assert any("DRY_RUN buy VOO" in log for log in trade_logs)
+    assert not any(order["symbol"] == "BOXX" for order in summary["orders_submitted"])
+    assert summary["safe_haven_cash_substituted_symbols"] == ["BOXX"]
+    assert summary["realized_safe_haven_weight"] == 0.0
+    boxx_row = next(row for row in summary["target_vs_current"] if row["symbol"] == "BOXX")
+    assert boxx_row["target_weight"] == 0.0
+
+
 def test_execute_rebalance_sells_cash_sweep_symbol_when_buying_power_is_short(monkeypatch, tmp_path):
     class FakeIB:
         def __init__(self):
@@ -645,7 +696,7 @@ def accountValues(self):
         FakeIB(),
         {"VOO": 0.6, "BOXX": 0.4},
         {},
-        {"equity": 1000.0, "buying_power": 1000.0},
+        {"equity": 3000.0, "buying_power": 3000.0},
         fetch_quote_snapshots=lambda *_args, **_kwargs: {},
         submit_order_intent=lambda *_args, **_kwargs: None,
         order_intent_cls=OrderIntent,

tests/test_runtime_config_support.py

@@ -6,6 +6,7 @@
 import pytest
 
 from runtime_config_support import (
+    DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD,
     load_platform_runtime_settings,
     parse_account_group_configs,
 )
@@ -121,6 +122,7 @@ def test_load_platform_runtime_settings_uses_minimal_group_config(monkeypatch):
     assert settings.dry_run_only is False
     assert settings.quantity_step == 1.0
     assert settings.min_order_notional == 50.0
+    assert settings.safe_haven_cash_substitute_threshold_usd == DEFAULT_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD
     assert settings.account_group == "paper"
     assert settings.service_name is None
     assert settings.account_ids == ()
@@ -198,11 +200,13 @@ def test_load_platform_runtime_settings_uses_whole_share_quantity_step(monkeypat
     monkeypatch.setenv("ACCOUNT_GROUP", "paper")
     monkeypatch.setenv("IB_ACCOUNT_GROUP_CONFIG_JSON", MINIMAL_GROUP_JSON)
     monkeypatch.setenv("IBKR_MIN_ORDER_NOTIONAL_USD", "5")
+    monkeypatch.setenv("IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD", "750")
 
     settings = load_platform_runtime_settings(project_id_resolver=lambda: "project-1")
 
     assert settings.quantity_step == 1.0
     assert settings.min_order_notional == 5.0
+    assert settings.safe_haven_cash_substitute_threshold_usd == 750.0
 
 
 def test_load_platform_runtime_settings_reads_ibkr_strategy_plugin_mounts(monkeypatch):
@@ -427,6 +431,7 @@ def test_print_strategy_switch_env_plan_for_tqqq_growth_income():
     assert plan["requires_strategy_config_path"] is False
     assert json.loads(plan["set_env"]["RUNTIME_TARGET_JSON"])["strategy_profile"] == "tqqq_growth_income"
     assert "ACCOUNT_GROUP" in plan["keep_env"]
+    assert "IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD" in plan["optional_env"]
     assert "IBKR_FEATURE_SNAPSHOT_PATH" in plan["remove_if_present"]