@senpi/runtime 3.0.0-dev.runtime-phase-2.20260623210537 → 3.0.1-dev.openclaw-upgrade-mai.20260625140818

package/examples/strategies/iguana/scanners/scan.py

@@ -0,0 +1,243 @@
+"""IGUANA — supervised external scanner entrypoint (XYZ macro index trend).
+
+Port of senpi-skills/iguana (producer v1.0.1, config v1.0.0) to the v2
+`scan(inputs, ctx)` contract. The daemon loop is gone — the runtime supervisor
+calls scan() every interval_seconds (300s).
+
+THE STRATEGY — the simplest possible XYZ equity exposure (ported VERBATIM; see
+scoring.py for the pure trend/scoring functions):
+
+  1. Whitelist — the two broad XYZ indices {xyz:SP500, xyz:XYZ100}. No
+     stock-picking, no commodities, no pre-IPO.
+  2. Per non-held index, fetch 4h candles (market_get_asset_data,
+     candle_intervals ["4h"]) and compute a 4-day trend strength: the % change
+     of the latest 4h close vs the close `trendLookbackBars` (24) bars ago.
+  3. Pick the index with the highest |strength| above `minTrendPct` (1.5%).
+  4. Score it: base 3, +2 if |strength| >= `strongTrendPct` (4.0%), +1 if volume
+     is rising (> 15% over 6 bars). Emit only if score >= `minScore` (4).
+  5. Direction = sign of the trend (LONG if up, SHORT if down).
+  6. Emit AT MOST ONE signal per tick (one decision, two assets).
+
+DESIGN CHOICE — emit best-only vs runtime-owns-slots. Turbine/spider emit ALL
+gated candidates and let the runtime apply the slot ceiling. IGUANA is
+deliberately different: it emits AT MOST ONE signal per tick (the single
+strongest index trend). This is the strategy, not an oversight — iguana's whole
+thesis is "two assets, ONE decision per tick," and the source producer picked the
+single strongest trend and pushed exactly one signal. Keeping `slots: 1` in the
+recipe matches the single-position thesis. We preserve the per-tick <=1 emission
+ceiling on purpose.
+
+Sizing — carried on each signal's data{} so the OPEN_POSITION rule action sizes
+identically to the source:
+  - marginUsd = round(account_value * marginPct, 2), marginPct 0.20. Dual-DEX
+    equity is collapsed via max() (NOT sum()) — one cross-margined wallet, two
+    sub-DEX views; summing double-counts free balance -> 2x sizing.
+  - leverage = min(config leverage 3, MAX_LEVERAGE 5).
+
+FLAGS — behaviors that changed under the v2 contract (NOT silent drops):
+
+  1. Daemon loop / producer_daemon — DROPPED. The runtime supervises this module
+     and calls scan() each interval_seconds. scan() is single-pass and SYNC.
+
+  2. push_signal / ingest POST — DROPPED. scan() returns a plain list[dict]; the
+     scaffold owns delivery, dedup (signal_id), and the wire envelope. The
+     source's [0,1] normalized wire score (min(score/6, 1.0)) is NOT recomputed
+     here — the raw additive score rides on data{} and the scaffold/runtime own
+     wire scoring. (SCORE_NORMALIZATION_DIVISOR is kept in scoring.py for parity.)
+
+  3. recent-signals.json 240s dedup — MOVED to ctx.state. The per-coin 240s
+     recent-signal dedup that the source kept in a JSON file lives in ctx.state
+     now: each tick reads the latest {coin: ts} map, prunes by the source's
+     window (4 × TTL), skips coins signaled within TTL, stamps the chosen
+     candidate, and appends the updated map for next tick.
+
+  4. ONLY read-only MCP calls. scan() never opens/closes/cancels — it produces
+     signals. (A test asserts no create/close/cancel tool is ever called.)
+
+MCP tools used (all read-only): market_get_asset_data (4h candles),
+strategy_get_clearinghouse_state.
+
+State (in ctx.state, newest record wins): {"recent": {COIN: epoch_seconds}}.
+"""
+
+import sys
+import time
+
+import scoring
+
+RECENT_SIGNAL_TTL_SEC = 240    # source iguana_config.RECENT_SIGNAL_TTL_SEC
+
+
+# ── MCP data fetchers (route the producer's calls through ctx.senpi_mcp) ──
+
+def _fetch_candles(ctx, asset):
+    """market_get_asset_data(4h) -> list of 4h candle dicts (or []).
+
+    Verbatim parse from iguana-producer.fetch_candles: honors the `success`
+    flag and digs into data.candles["4h"].
+    """
+    try:
+        data = ctx.senpi_mcp.call_tool("market_get_asset_data", {
+            "asset": asset,
+            "candle_intervals": ["4h"],
+            "include_funding": False,
+            "include_order_book": False,
+        })
+    except Exception:
+        return []
+    if not data or (isinstance(data, dict) and not data.get("success", True)):
+        return []
+    d = data.get("data", data) if isinstance(data, dict) else data
+    if not isinstance(d, dict):
+        return []
+    candles = d.get("candles", {}) or {}
+    if not isinstance(candles, dict):
+        return []
+    return candles.get("4h", []) or []
+
+
+def _get_account(ctx):
+    """(account_value, held_assets) from strategy_get_clearinghouse_state.
+
+    Dual-DEX equity collapse: account_value via max() across main/xyz sections
+    (two views of ONE cross-margined wallet — summing double-counts free
+    balance -> 2x sizing). Verbatim from iguana_config.get_positions.
+    """
+    try:
+        ch = ctx.senpi_mcp.call_tool("strategy_get_clearinghouse_state",
+                                     {"strategy_wallet": ctx.wallet})
+    except Exception:
+        return 0.0, []
+    if not ch:
+        return 0.0, []
+    data = ch.get("data", ch) if isinstance(ch, dict) else ch
+    if not isinstance(data, dict):
+        return 0.0, []
+    account_value = 0.0
+    held = []
+    for section in ("main", "xyz"):
+        s = data.get(section, {})
+        if not isinstance(s, dict):
+            continue
+        ms = s.get("marginSummary", {})
+        account_value = max(account_value, scoring._f(ms, "accountValue"))
+        for ap in s.get("assetPositions", []) or []:
+            pos = ap.get("position", ap)
+            if scoring._f(pos, "szi") == 0:
+                continue
+            coin = pos.get("coin", "")
+            if coin:
+                held.append(coin)
+    return account_value, held
+
+
+# ── ctx.state I/O (per-coin 240s recent-signal dedup) ──
+
+def _load_recent(ctx):
+    if ctx.state is None or len(ctx.state) == 0:
+        return {}
+    last = ctx.state.last() or {}
+    recent = last.get("recent", {})
+    return dict(recent) if isinstance(recent, dict) else {}
+
+
+def _prune_recent(recent, now):
+    """Drop entries older than the source window (4 × TTL). Verbatim from
+    iguana_config._prune_recent_signals."""
+    cutoff = now - (RECENT_SIGNAL_TTL_SEC * 4)
+    return {k: v for k, v in recent.items() if v >= cutoff}
+
+
+def _was_recently_signaled(recent, coin, now, ttl_sec=RECENT_SIGNAL_TTL_SEC):
+    """True if `coin` was signaled within `ttl_sec`. Verbatim window logic from
+    iguana_config.was_recently_signaled."""
+    if not coin:
+        return False
+    last = recent.get(coin.upper())
+    if last is None:
+        return False
+    return (now - last) < ttl_sec
+
+
+def scan(inputs, ctx):
+    now = time.time()
+    whitelist = inputs.get("whitelist", scoring.DEFAULT_WHITELIST)
+    lookback = int(inputs.get("trendLookbackBars", scoring.DEFAULT_TREND_LOOKBACK))
+    min_pct = float(inputs.get("minTrendPct", scoring.DEFAULT_MIN_TREND_PCT))
+    min_score = int(inputs.get("minScore", scoring.DEFAULT_MIN_SCORE))
+    margin_pct = float(inputs.get("marginPct", scoring.DEFAULT_MARGIN_PCT))
+    leverage = min(int(inputs.get("leverage", scoring.DEFAULT_LEVERAGE)),
+                   scoring.MAX_LEVERAGE)
+
+    account_value, held_assets = _get_account(ctx)
+    if account_value <= 0:
+        return []
+    held_set = {h.upper() for h in held_assets}
+
+    recent = _prune_recent(_load_recent(ctx), now)
+
+    # config-shaped knobs for build_thesis (reads minTrendPct / strongTrendPct).
+    thesis_config = {
+        "minTrendPct": min_pct,
+        "strongTrendPct": float(inputs.get("strongTrendPct",
+                                           scoring.DEFAULT_STRONG_TREND_PCT)),
+        "minScore": min_score,
+    }
+
+    # Compute 4d trend strength for each non-held, non-recently-signaled index.
+    candles_by_asset = {}
+    strength_by_asset = {}
+    for asset in whitelist:
+        if asset.upper() in held_set or _was_recently_signaled(recent, asset, now):
+            continue
+        candles = _fetch_candles(ctx, asset)
+        if len(candles) <= lookback:
+            continue
+        closes = [scoring._f(c, "close", "c") for c in candles]
+        candles_by_asset[asset] = candles
+        strength_by_asset[asset] = scoring.trend_strength(closes, lookback)
+
+    out = []
+    picked = scoring.pick_strongest_trend(strength_by_asset, min_pct)
+    if picked is not None:
+        asset, strength = picked
+        thesis = scoring.build_thesis(asset, strength, candles_by_asset[asset],
+                                      thesis_config)
+        if thesis is not None and thesis["score"] >= min_score:
+            coin = thesis["coin"]
+            if coin.upper() not in held_set:
+                margin_usd = round(account_value * margin_pct, 2)
+                # Stamp the 240s recent-signal dedup so we don't re-emit.
+                recent[coin.upper()] = now
+                out.append({
+                    "asset": coin,
+                    "direction": thesis["direction"],
+                    "marginUsd": float(margin_usd),
+                    "leverage": float(leverage),
+                    "data": {
+                        "score": thesis["score"],
+                        "direction": thesis["direction"],
+                        "reasons": thesis["reasons"],
+                        "trendPct": thesis.get("trend_pct") or 0.0,
+                        "volumeTrendPct": thesis.get("volume_trend_pct") or 0.0,
+                        "heldAssets": held_assets,
+                    },
+                })
+
+    # Persist the pruned + updated dedup map for next tick.
+    # If this append fails (e.g. state_history_max_count is 0/unset so append
+    # raises, or a transient persist error), the next tick reloads stale dedup
+    # state and may re-emit already-suppressed signals. Log-and-continue: don't
+    # crash the tick, but make the failure visible on stderr (the runtime
+    # supervisor captures the scaffold child's stderr) instead of swallowing it.
+    if ctx.state is not None:
+        try:
+            ctx.state.append({"recent": recent})
+        except Exception as exc:
+            print(
+                f"[iguana.scan] WARNING: dedup-state append failed; next tick "
+                f"may re-emit suppressed signals: {exc!r}",
+                file=sys.stderr,
+            )
+
+    return out

package/examples/strategies/iguana/scanners/scoring.py

@@ -0,0 +1,152 @@
+"""IGUANA — pure index-trend functions (port of iguana-producer.py v1.0.1).
+
+Ported VERBATIM from senpi-skills/iguana/scripts/iguana-producer.py (the pure
+trend / scoring helpers, already unit-tested in that repo's tests/test_signal.py)
+and iguana_config.py. No I/O, no MCP, no daemon — pure and unit-testable.
+`scan.py` fetches 4h candles via ctx.senpi_mcp and hands them to these helpers.
+
+THE STRATEGY — XYZ macro index trend (the simplest XYZ equity exposure):
+trend-follow the broad indices `xyz:SP500` + `xyz:XYZ100`. No stock-picking, no
+commodities, no pre-IPO. Two assets, ONE decision per tick. Each tick computes a
+4-day trend strength (% change of the latest 4h close vs the close
+`trendLookbackBars` (24 = 4 days) ago), picks the stronger move past
+`minTrendPct` (1.5%), and trades in its direction. Score = base 3, +2 if the move
+is strong (>= `strongTrendPct` 4.0%), +1 if volume is rising (> 15% over 6 bars);
+floor `minScore` 4. Closest thing to an index fund, but 24/7 on Hyperliquid.
+
+Constants below are the source defaults (iguana-producer.py + config v1.0.0).
+"""
+
+# ── Constants (verbatim from producer + config v1.0.0) ──
+
+MAX_LEVERAGE = 5
+DEFAULT_LEVERAGE = 3
+DEFAULT_MIN_SCORE = 4
+
+DEFAULT_WHITELIST = ["xyz:SP500", "xyz:XYZ100"]
+DEFAULT_TREND_LOOKBACK = 24    # 24 × 4h bars = 4 days
+DEFAULT_MIN_TREND_PCT = 1.5    # minimum |4-day move| to call it a trend
+DEFAULT_STRONG_TREND_PCT = 4.0
+DEFAULT_MARGIN_PCT = 0.20
+
+# Score normalization divisor used by the source when posting the [0,1] wire
+# score (min(score / 6, 1.0)). Kept for parity — the scaffold/runtime own wire
+# scoring now; the raw additive score rides on data{}.
+SCORE_NORMALIZATION_DIVISOR = 6.0
+
+
+def _f(c, primary, alt=None, default=0.0):
+    """Pull a numeric field from a candle dict, trying `primary` then `alt`.
+
+    Verbatim from iguana-producer._f — candle responses use either long keys
+    (close/volume) or short keys (c/v) depending on the source shape.
+    """
+    val = c.get(primary)
+    if val is None and alt:
+        val = c.get(alt)
+    try:
+        return float(val if val is not None else default)
+    except (TypeError, ValueError):
+        return default
+
+
+# ═══════════════════════════════════════════════════════════════
+# Pure index-trend logic (unit-tested in the source tests/test_signal.py)
+# ═══════════════════════════════════════════════════════════════
+
+def trend_strength(closes, lookback):
+    """% change of the latest close vs the close `lookback` bars ago.
+    None if insufficient data or the reference price is non-positive.
+
+    Verbatim from iguana-producer.trend_strength.
+    """
+    if not closes or len(closes) <= lookback:
+        return None
+    ref = closes[-(lookback + 1)]
+    latest = closes[-1]
+    if ref is None or ref <= 0:
+        return None
+    return ((latest - ref) / ref) * 100.0
+
+
+def trend_direction(strength, min_pct):
+    """Direction implied by trend strength. None if magnitude below threshold.
+
+    Verbatim from iguana-producer.trend_direction.
+    """
+    if strength is None or abs(strength) < min_pct:
+        return None
+    return "LONG" if strength > 0 else "SHORT"
+
+
+def pick_strongest_trend(per_asset_strength, min_pct):
+    """Among {asset: strength}, return the asset with the highest |strength|
+    above min_pct. Returns (asset, strength) or None.
+
+    Verbatim from iguana-producer.pick_strongest_trend.
+    """
+    best, best_mag = None, -1.0
+    for asset, strength in per_asset_strength.items():
+        if strength is None:
+            continue
+        mag = abs(strength)
+        if mag < min_pct:
+            continue
+        if mag > best_mag:
+            best_mag, best = mag, (asset, strength)
+    return best
+
+
+def volume_trend(candles, lookback=6):
+    """% change of the recent half vs the earlier half of the last `lookback`
+    candle volumes. 0.0 when there is insufficient data.
+
+    Verbatim from iguana-producer.volume_trend.
+    """
+    if len(candles) < lookback:
+        return 0.0
+    vols = [_f(c, "volume", "v") for c in candles[-lookback:]]
+    half = lookback // 2
+    if half <= 0:
+        return 0.0
+    recent = sum(vols[-half:]) / half
+    earlier = sum(vols[:half]) / half
+    if earlier <= 0:
+        return 0.0
+    return ((recent - earlier) / earlier) * 100
+
+
+def build_thesis(asset, strength, candles, config):
+    """Build the index-trend thesis (direction + additive score + reasons).
+
+    Score: base 3 (trend above min), +2 if |strength| >= strongTrendPct, +1 if
+    volume_trend > 15%. Returns the thesis dict or None when the direction gate
+    (|strength| >= minTrendPct) is not cleared. Verbatim from
+    iguana-producer.build_thesis.
+    """
+    min_pct = float(config.get("minTrendPct", DEFAULT_MIN_TREND_PCT))
+    strong_pct = float(config.get("strongTrendPct", DEFAULT_STRONG_TREND_PCT))
+
+    direction = trend_direction(strength, min_pct)
+    if direction is None:
+        return None
+
+    vol = volume_trend(candles)
+
+    score = 3   # base — trend strength above min
+    reasons = [f"{asset}_4d_trend_{strength:+.1f}%"]
+    if abs(strength) >= strong_pct:
+        score += 2
+        reasons.append(f"trend_strong_{strength:+.1f}%")
+    if vol > 15:
+        score += 1
+        reasons.append(f"vol_rising_{vol:+.0f}%")
+
+    return {
+        "coin": asset,
+        "direction": direction,
+        "score": score,
+        "reasons": reasons,
+        "trend_pct": round(strength, 2),
+        "volume_trend_pct": round(vol, 2),
+    }

package/examples/strategies/raptor/README.md

@@ -0,0 +1,156 @@
+# RAPTOR (v2 supervised demo)
+
+Raptor is a **single-wallet, single-recipe** whale **copy-follow** strategy: it
+finds currently-winning quality traders, takes their strongest-conviction
+position when smart money agrees, and rides it with a patient-but-bounded DSL
+exit.
+
+Ported from `senpi-skills/raptor` (producer v4.0.1, config v3.1) to the runtime
+v2 supervised external-scanner contract. The standalone producer daemon is gone;
+the runtime supervises `scanners/scan.py` and calls `scan()` every
+`interval_seconds` (180s).
+
+> **DOC-vs-CODE warning.** The `senpi-skills/raptor` SKILL/README docs are
+> **stale** — they describe a $2M trader gate and 0.40 concentration. The
+> **code** (config v3.1 + producer constants) is authoritative and is what this
+> port uses: trader delta gate **$500k**, position gate **$100k**, concentration
+> **0.35**, SM **pct ≥ 2 / traders ≥ 10**, whale entry-discipline **5%**,
+> `minScore` **6**. Every threshold below was resolved to the code.
+
+## The strategy (`scanners/scan.py`)
+
+Quality-first copy-follow pipeline, run once per tick:
+
+1. **Quality hot traders** — `discovery_get_top_traders(WEEKLY,
+   sort PROFIT_AND_LOSS_UNREALIZED, consistency ELITE/RELIABLE,
+   open_position_filter, limit 20)`; keep traders whose **unrealized delta-pnl
+   ≥ $500k**, sorted desc. Scan the top **10** for positions.
+2. **Strongest position** — per trader, `leaderboard_get_trader_positions`; pick
+   the position with the largest **|delta_pnl| (≥ $100k)**.
+3. **Concentration** — `best |delta_pnl| / total |delta_pnl| ≥ 0.35` (one
+   conviction bet, not a diversified book).
+4. **Smart-money alignment** — `leaderboard_get_markets`; the asset must show
+   **SM pct ≥ 2.0**, **traders ≥ 10**, and direction matching the whale's.
+5. **Whale entry-discipline** — `market_get_prices`; **skip if the price already
+   ran > 5%** from the whale's entry in the whale's direction (don't buy the top).
+6. **Additive score (max ~16)** — TCS + trader-$ tier + ROI + concentration +
+   SM strength + 4h/1h price confirm + 15m contribution + a better-than-whale
+   entry-edge bonus. (All tiers ported verbatim — see `scoring.py`.)
+7. **Emit the single best candidate**, and only if `score ≥ 6`.
+
+Sizing rides on each signal's `data{}` so the `OPEN_POSITION` rule action sizes
+identically to the source:
+
+- **marginUsd** = `account_value × margin_pct`, `margin_pct` **0.25** (**0.35**
+  if `score ≥ 10`). Dual-DEX equity is collapsed via **`max()` not `sum()`** —
+  one cross-margined wallet, two sub-DEX views.
+- **leverage** = conviction tier (**≥10 → 10x, ≥8 → 8x, ≥6 → 7x**), clamped to
+  the per-asset Hyperliquid venue max via `strategy_get_asset_trading_limits`.
+
+**XYZ is banned** (config `smAlignment.xyzBanned`): xyz-dex SM markets and `xyz:`
+positions are dropped.
+
+MCP tools used (all **read-only**): `discovery_get_top_traders`,
+`leaderboard_get_trader_positions`, `leaderboard_get_markets`,
+`market_get_prices`, `strategy_get_asset_trading_limits`,
+`strategy_get_clearinghouse_state`.
+
+State (the per-`(trader, asset)` **4h event dedup** map) lives in `ctx.state`
+(the source kept it in `seen-events.json`).
+
+## Why raptor emits at most one signal per tick
+
+Turbine/spider emit **all** gated candidates and let the runtime apply the slot
+ceiling. **Raptor is deliberately different: it emits ≤ 1 signal per tick** — the
+single highest-score whale-aligned setup. This is the **strategy**, not an
+oversight: raptor's thesis is "follow the single strongest conviction signal
+right now," and the source producer pushed exactly one signal per tick after
+sorting candidates by score. `slots: 2` still lets a prior position stay open
+while a later tick emits the next-best; the runtime owns whether the second slot
+fills across ticks.
+
+## Layout
+
+```
+raptor/
+├── README.md
+├── recipe.yaml            # the single recipe (path: ./scanners, entrypoint: scan.py)
+└── scanners/
+    ├── scan.py            # scan(inputs, ctx) entrypoint (whale copy-follow pipeline)
+    └── scoring.py         # pure parsing/gating/scoring functions (unit-tested)
+```
+
+## Environment variables
+
+| Variable           | Required | Purpose |
+|--------------------|----------|---------|
+| `RAPTOR_WALLET`    | yes      | Raptor's strategy wallet |
+| `SENPI_API_KEY`    | yes      | MCP auth for `ctx.senpi_mcp` (injected into the scaffold child) |
+| `SENPI_MCP_URL`    | yes      | MCP server URL |
+| `TELEGRAM_CHAT_ID` | optional | Notifications |
+
+## Install / run
+
+```bash
+RAPTOR_WALLET=0x... \
+SENPI_API_KEY=... SENPI_MCP_URL=https://mcp.prod.senpi.ai/mcp \
+  openclaw senpi run examples/strategies/raptor/recipe.yaml
+```
+
+## Fidelity notes
+
+Source behaviors that changed (or did not map 1:1) under the v2 contract.
+Nothing load-bearing was silently dropped.
+
+### Dropped: the daemon loop + ingest POST
+
+The source ran a `producer_daemon(interval_seconds=180)` that POSTed signals to
+the ingest endpoint via `push_signal`. Under v2 the runtime **supervises** this
+module and calls `scan()` once per `interval_seconds`; `scan()` is **single-pass
+and synchronous** and **returns a `list[dict]`**. The scaffold owns delivery,
+the wire envelope, and `signal_id` dedup. The source's normalized [0,1] wire
+score (`min(score / 16, 1.0)`) is **not** recomputed in `scan()` — the raw
+additive score rides on `data{}` and the runtime owns wire scoring. (The
+`16.0` divisor is preserved in `scoring.py` for parity.)
+
+### Moved to `ctx.state`: the 4h event dedup
+
+The per-`(trader, asset)` **4h** event dedup that the source kept in
+`seen-events.json` now lives in `ctx.state`: each tick reads the latest
+`{key: ts}` map, **prunes** it by the 4h window, applies it, **stamps** the
+chosen candidate's `(trader, asset)`, and appends the updated map for the next
+tick. The dedup key is verbatim — first 10 chars of the lowercased trader
+address + the asset symbol.
+
+### Action gate: `decision_mode: llm` → `rule`
+
+The source `OPEN_POSITION` action used `decision_mode: llm` with a copy-verbatim
+pass-through prompt and a pinned confidence — a rule wearing an LLM costume. This
+recipe uses `decision_mode: rule` directly.
+
+### Thresholds resolved to CODE (not stale docs)
+
+The `senpi-skills/raptor` SKILL/README claimed a **$2M** trader gate and **0.40**
+concentration. The **code** (config v3.1 + producer constants) uses **$500k** and
+**0.35** — those are the values ported. Every other gate/scoring tier
+(`minPositionPnl` $100k, SM pct 2 / traders 10, entry-discipline 5%, `minScore`
+6, trader tiers $1.5M/$3M, leverage 7/8/10x, margin 0.25/0.35) maps cleanly and
+is carried verbatim.
+
+### DSL preset maps cleanly
+
+The source DSL preset maps 1:1 to the v2 schema (no dropped tiers): hard_timeout
+360m, weak_peak 60m@2.5, dead_weight 40m, phase1 max_loss 25 / retrace 10, and a
+5-tier phase2 (8/25 · 15/50 · 25/65 · 40/80 · 60/88).
+
+### Guard rails: minutes/hours → seconds
+
+The v2 schema uses integer seconds everywhere. `cooldown_minutes 30` →
+`cooldown_seconds 1800`; `per_asset_cooldown_minutes 120` →
+`per_asset_cooldown_seconds 7200`; `data_retention_hours 72` →
+`data_retention_seconds 259200`.
+
+### Only read-only MCP calls
+
+`scan.py` never opens, closes, or cancels — it produces signals. A test asserts
+no `create_position` / `close_position` / `cancel_order` tool is ever called.