@senpi/runtime 3.0.9-dev.feat-strategy-compos.20260721003344 → 3.0.9-dev.feat-strategy-compos.20260722213012

package/dist/composer/verbs/review.py

@@ -0,0 +1,724 @@
+"""review — retrospective TRADE-QUALITY analysis for ``composer review [<strategy>]`` (slice J8).
+
+``composer review`` is the SINGLE PRODUCER of trade-quality analysis: it absorbs the ENGINE of the
+separately-versioned ``senpi-improve-trades`` skill (its ``review.py``) so that script can be deleted
+in a follow-up slice. Per strategy it reconstructs the CLOSED-trade record (count / win rate / realized
+PnL), enriches each exit with the box EVENT LOG's exit reason, tallies leak findings, and — when the
+graph carries a ``metadata.spec.thesis`` — quotes that mandate next to the observed behaviour. Bare
+``composer review`` sweeps every accountable strategy and adds the cross-strategy realized-PnL
+aggregate (the realized-PnL / trade-history views the retired ``senpi-portfolio`` skill left un-homed).
+
+It corrects the improve-trades engine's TWO field-proven defects BY CONSTRUCTION:
+
+  1. ZERO-TRADES LABEL ARTIFACT — review.py set ``meta.telemetry_source="unavailable"`` whenever zero
+     events enriched zero closed trades, so a user with NO closed trades read "Telemetry is
+     unavailable" on a perfectly healthy pipeline. Here a strategy with no closed trades renders an
+     honest "no closed trades yet — nothing to review", and telemetry availability is NEVER conflated
+     with nothing-to-enrich: the two are separate, separately-reported facts.
+  2. CLI COLD-BOOT TIMEOUT — review.py shelled ``openclaw senpi events --runtime <id>`` per strategy
+     (review.py:485), each a full CLI + plugins + OTel boot (~10-15s) fanned 8-wide, so every read
+     timed out and the engine reported telemetry unavailable while the data was fine. This verb makes
+     ZERO shell-outs to the openclaw CLI for events: the rim serves the per-runtime event rings
+     IN-PROCESS via the ``events`` section of the live document (composer-live-read.ts::getEventsByRuntime).
+     When that section is absent (offline / direct invocation) events render "unavailable (no live
+     channel — run via the rim)" — there is deliberately NO events subprocess fallback (unlike
+     state/list, an event ring has no sanctioned cold-boot path for a hot loop).
+
+FAIL-LOUD honesty doctrine (settled across the composer verbs): every unavailable input renders
+"unavailable (reason)"; a per-strategy transport failure (history read) degrades THAT strategy, never
+the sweep; zero closed trades is the honest empty message; and every quoted figure NAMES its source
+(backend trade history / box event log).
+
+All I/O is an INJECTABLE SEAM (mirroring ``_box``/``_live``): ``history_fn`` (wallet -> closed-trade
+rows) and ``events_fn`` (the live document's ``events`` section) are faked in tests; production wires
+``default_closed_history`` (the in-process MCP seam) and the live-document reader. No test spawns
+anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from . import _box
+from ._box import McpFn, default_mcp_call
+from ._layout import canonical_graph_path
+from ._live import LiveState
+from .portfolio import _effective_install, _resolve_wallet, enumerate_strategies
+from .status import run_status
+
+# The named sources every figure is attributed to (printed so an operator always knows the producer).
+SRC_HISTORY = "backend trade history"          # discovery_get_trader_history (onchain closed ledger)
+SRC_EVENTS = "box event log"                   # the runtime's on-disk event ring (dsl/position/order/…)
+
+CLOSED_HISTORY_PULL = 100                       # closed positions to pull per wallet (review.py parity)
+
+# EXIT attribution — the exit events a closed trade is matched against (references/event-log.md shapes).
+_EXIT_EVENT_NAMES = ("dsl.closed", "position.closed")
+EXIT_MATCH_WINDOW_MS = 120000.0                 # ±2-min asset+time fallback when there is no order id
+
+# PREMATURE-exit label (folded from review.py::_is_premature_exit) — the "shaken out too early" cohort.
+_PREMATURE_TERMINALS = ("trailing_floor", "weak_peak", "max_retrace")
+_PREMATURE_TIER_MAX = 1
+_PREMATURE_ROE_MAX = 5.0
+
+# LEAK scan (folded from review.py::_scan_leak_and_fill_events, minus the maker/taker fee tally — a
+# separate concern deferred). Protection gaps + failed orders + risk halts, from the same event ring.
+_LEAK_ORDER_FAILED = "order.failed"
+_LEAK_PROTECTION = ("dsl.sl_sync_failed", "dsl.handoff_failed")
+_LEAK_PAUSED = "runtime.paused"
+_LEAK_SAMPLE_CAP = 5
+
+
+# --------------------------------------------------------------------------- seams
+
+# A wallet -> raw closed-position rows reader (discovery_get_trader_history). Injectable so tests
+# fake it; production wires ``default_closed_history`` (the in-process MCP seam). Returns the raw
+# rows; parsing lives in ``_parse_closed_trades`` so the seam stays a thin transport.
+HistoryFn = Callable[[str], list[dict]]
+
+# A reader for the live document's ``events`` section (``{ok, by_runtime}`` | ``{ok:false, reason}``),
+# or None when no live channel was handed down (offline / direct CLI). NEVER a subprocess (hard rule).
+EventsFn = Callable[[], Optional[dict]]
+
+
+class HistoryUnavailable(Exception):
+    """A closed-history transport/credential failure for ONE wallet — carried so the sweep can render
+    that strategy's history as "unavailable (reason)" and move on, never crash the whole review."""
+
+
+def default_closed_history(wallet: str, mcp_fn: McpFn = default_mcp_call) -> list[dict]:
+    """Production :data:`HistoryFn`: the wallet's closed-position ledger via the in-process MCP seam
+    (``discovery_get_trader_history`` — the SAME tool review.py read, reused through ``_box``'s
+    streamable-HTTP client, NOT a CLI boot). Raises :class:`HistoryUnavailable` on any transport /
+    credential / shape failure so the caller renders it LOUD (never a fabricated empty)."""
+    try:
+        raw = mcp_fn("discovery_get_trader_history", trader_address=wallet,
+                     sort_by="CLOSED_TIME", sort_direction="DESC", limit=CLOSED_HISTORY_PULL)
+    except _box.McpCredsMissing as e:
+        raise HistoryUnavailable(f"MCP credentials missing ({e})") from e
+    except _box.McpError as e:
+        raise HistoryUnavailable(f"MCP error reading trade history ({e})") from e
+    except Exception as e:  # noqa: BLE001 — a surprise transport fault is a datum, not a crash
+        raise HistoryUnavailable(f"could not read trade history ({e})") from e
+    data = _ok(raw)
+    if data is None:
+        raise HistoryUnavailable("trade history returned no data")
+    rows = data if isinstance(data, list) else _field(
+        data, "closedPositions", "closed_positions", "positions", default=[])
+    return [r for r in rows if isinstance(r, dict)] if isinstance(rows, list) else []
+
+
+def default_events_section() -> Optional[dict]:
+    """Production :data:`EventsFn`: the ``events`` section of the rim-served live document
+    (``SENPI_LIVE_FILE``). None when there is no live document at all OR it carries no ``events``
+    section (a direct/offline invocation) — the caller renders events "unavailable (no live channel)".
+    NEVER shells openclaw (the hard rule: an event ring has no sanctioned cold-boot path here)."""
+    doc = _box.load_live_document()
+    if not isinstance(doc, dict):
+        return None
+    section = doc.get("events")
+    return section if isinstance(section, dict) else None
+
+
+# --------------------------------------------------------------------------- guarded IO (folded from review.py)
+
+def _ok(resp):
+    if isinstance(resp, dict):
+        if resp.get("success") is False:
+            return None
+        return resp.get("data", resp)
+    return resp
+
+
+def _num(v):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _f(d, *keys, default=0.0):
+    if isinstance(d, dict):
+        for k in keys:
+            if k in d and d[k] is not None:
+                n = _num(d[k])
+                if n is not None:
+                    return n
+    return default
+
+
+def _field(d, *names, default=None):
+    if isinstance(d, dict):
+        for n in names:
+            if n in d and d[n] is not None:
+                return d[n]
+    return default
+
+
+def _ms(ts):
+    """Normalize a Unix timestamp to MILLISECONDS (folded from review.py::_ms — a seconds-valued
+    closeTime below ~1e12 is scaled ×1000, else it reads as pre-window and every trade drops)."""
+    n = _num(ts)
+    if n is None:
+        return None
+    return n * 1000.0 if n < 1e12 else n
+
+
+def _direction(rec, szi, entry_px, exit_px, pnl):
+    """Direction of a CLOSED trade (folded from review.py::_direction): explicit field → non-zero
+    szi sign → derive from realized PnL vs the price move. None when nothing resolves it."""
+    d = str(_field(rec, "dir", "side", "direction", "positionSide", default="") or "").strip().lower()
+    if d in ("long", "buy", "b", "bid", "l"):
+        return "long"
+    if d in ("short", "sell", "a", "ask", "s"):
+        return "short"
+    if szi and szi != 0:
+        return "long" if szi > 0 else "short"
+    move = (exit_px - entry_px) if (entry_px is not None and exit_px is not None) else None
+    if move and pnl:
+        return "long" if ((move > 0) == (pnl > 0)) else "short"
+    return None
+
+
+def _parse_closed_trades(rows: list[dict]) -> list[dict]:
+    """Map raw discovery ``closedPositions`` rows into the compact trade shape the review reasons on
+    (folded from review.py::fetch_closed_trades, minus the window filter — the composer verb reviews
+    the recent closed ledger as a whole). Each trade: asset / direction / size / entry_px / exit_px /
+    realized_pnl / open_time / close_time / closed_order_id. Sorted newest-close first."""
+    trades: list[dict] = []
+    for p in rows:
+        if not isinstance(p, dict):
+            continue
+        szi = _f(p, "szi", "size", default=0.0)
+        entry_px = _num(_field(p, "entryPx", "entry_px"))
+        exit_px = _num(_field(p, "exitPx", "exit_px"))
+        pnl = round(_f(p, "realizedPnl", "realized_pnl", default=0.0), 2)
+        trades.append({
+            "asset": _field(p, "coin", "coinDisplayName", "asset"),
+            "direction": _direction(p, szi, entry_px, exit_px, pnl),
+            "size": abs(szi),
+            "entry_px": entry_px,
+            "exit_px": exit_px,
+            "realized_pnl": pnl,
+            "open_time": _ms(_field(p, "openTime", "open_time")),
+            "close_time": _ms(_field(p, "closeTime", "closed_time", "closeTimeMs")),
+            "closed_order_id": _field(p, "closedOrderId", "closed_order_id"),
+        })
+    trades.sort(key=lambda t: _num(t.get("close_time")) or 0, reverse=True)
+    return trades
+
+
+# --------------------------------------------------------------------------- event enrichment (folded from review.py)
+
+def _attr(ev, *keys, default=None):
+    attrs = ev.get("attrs") if isinstance(ev, dict) else None
+    if isinstance(attrs, dict):
+        for k in keys:
+            if k in attrs and attrs[k] is not None:
+                return attrs[k]
+    return default
+
+
+def _index_exit_events(events: list[dict]):
+    """Build the exit-event matcher (folded from review.py::_index_exit_events): by_order_id (exact)
+    + by_asset (UPPER(asset) -> [(ts_ms, event)] for the ±2-min fallback)."""
+    by_order_id, by_asset = {}, {}
+    for ev in events:
+        if str(ev.get("name") or "") not in _EXIT_EVENT_NAMES:
+            continue
+        oid = _attr(ev, "senpi.order.id")
+        if oid:
+            by_order_id[str(oid)] = ev
+        asset = _attr(ev, "senpi.asset", "senpi.signal.asset")
+        ts = _num(ev.get("ts"))
+        if asset is not None and ts is not None:
+            by_asset.setdefault(str(asset).upper(), []).append((ts, ev))
+    return by_order_id, by_asset
+
+
+def _exit_reason_from_event(ev) -> dict:
+    """Read a telemetry exit event into the exit-reason contract (folded from review.py). Handles
+    both ``dsl.closed`` (senpi.dsl.*) and ``position.closed`` (senpi.position.*) shapes."""
+    terminal = _attr(ev, "senpi.dsl.close_reason", "senpi.position.close_reason")
+    tier_index = _attr(ev, "senpi.dsl.tier_index")
+    roe = _attr(ev, "senpi.dsl.current_roe", "senpi.position.roe")
+    return {
+        "terminal": terminal,
+        "tier_index": _num(tier_index) if tier_index is not None else None,
+        "high_water_roe": _num(roe) if roe is not None else None,
+        "source": "telemetry",
+    }
+
+
+def _match_exit_event(trade, by_order_id, by_asset):
+    """Find the exit event for one trade (folded from review.py::_match_exit_event): exact order id →
+    else same asset + close_time within ±EXIT_MATCH_WINDOW_MS, nearest in time. None on no match."""
+    oid = trade.get("closed_order_id")
+    if oid and str(oid) in by_order_id:
+        return by_order_id[str(oid)]
+    asset = str(trade.get("asset") or "").upper()
+    close_ms = _num(trade.get("close_time"))
+    if not asset or close_ms is None:
+        return None
+    best, best_dist = None, None
+    for ts, ev in by_asset.get(asset, []):
+        dist = abs(ts - close_ms)
+        if dist <= EXIT_MATCH_WINDOW_MS and (best_dist is None or dist < best_dist):
+            best, best_dist = ev, dist
+    return best
+
+
+def _is_premature_exit(exit_reason) -> bool:
+    """The 'shaken out too early' label for one exit (folded verbatim in spirit from review.py):
+    terminal ∈ {trailing_floor, weak_peak, max_retrace}, OR a low tier (<=1) locked with a small
+    high-water ROE (<=~5%). Fail-soft: a missing/odd exit_reason → False (never invent an early exit)."""
+    if not isinstance(exit_reason, dict):
+        return False
+    terminal = str(exit_reason.get("terminal") or "")
+    if terminal in _PREMATURE_TERMINALS:
+        return True
+    tier = _num(exit_reason.get("tier_index"))
+    roe = _num(exit_reason.get("high_water_roe"))
+    if tier is not None and tier <= _PREMATURE_TIER_MAX and roe is not None and abs(roe) <= _PREMATURE_ROE_MAX:
+        return True
+    return False
+
+
+def _scan_leaks(events: list[dict]) -> dict:
+    """The leak rollup (folded from review.py::_scan_leak_and_fill_events, fee tally dropped):
+    failed orders / protection-sync gaps / risk halts, each ``{count, samples[]}``. Counts EXACT,
+    samples capped + illustrative. Fail-soft on any odd event shape."""
+    leaks = {"order_failed": {"count": 0, "samples": []},
+             "protection_gaps": {"count": 0, "samples": []},
+             "risk_halts": {"count": 0, "samples": []}}
+    for ev in events:
+        name = str(ev.get("name") or "")
+        if name == _LEAK_ORDER_FAILED:
+            cat = leaks["order_failed"]
+            cat["count"] += 1
+            if len(cat["samples"]) < _LEAK_SAMPLE_CAP:
+                cat["samples"].append({"asset": _attr(ev, "senpi.asset", "senpi.signal.asset"),
+                                       "reason": _attr(ev, "senpi.order.reason", "senpi.order.error_name")})
+        elif name in _LEAK_PROTECTION:
+            cat = leaks["protection_gaps"]
+            cat["count"] += 1
+            if len(cat["samples"]) < _LEAK_SAMPLE_CAP:
+                cat["samples"].append({"asset": _attr(ev, "senpi.asset", "senpi.signal.asset"), "event": name})
+        elif name == _LEAK_PAUSED:
+            cat = leaks["risk_halts"]
+            cat["count"] += 1
+            if len(cat["samples"]) < _LEAK_SAMPLE_CAP:
+                cat["samples"].append({"reason": _attr(ev, "senpi.pause.reason", "senpi.runtime.pause_reason",
+                                                        "senpi.reason")})
+    return leaks
+
+
+# --------------------------------------------------------------------------- thesis (the graph mandate)
+
+def _read_thesis(base_state_dir: str, strategy: str) -> Optional[str]:
+    """The strategy's declared mandate — ``metadata.spec.thesis`` from its canonical graph.yaml
+    (composer's OWN record; NOT the runtime registry review.py read). One line, quoted verbatim next
+    to observed behaviour — never interpreted/scored. None when there is no graph or no thesis key.
+    Tolerant + never raises (a missing/unreadable/hand-authored-minimal graph simply has no thesis)."""
+    import yaml
+
+    path = canonical_graph_path(base_state_dir, strategy)
+    try:
+        doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError, ValueError):
+        return None
+    if not isinstance(doc, dict):
+        return None
+    meta = doc.get("metadata")
+    spec = meta.get("spec") if isinstance(meta, dict) else None
+    if not isinstance(spec, dict):
+        return None
+    thesis = spec.get("thesis")
+    if isinstance(thesis, str) and thesis.strip():
+        return " ".join(thesis.split()).strip()
+    return None
+
+
+# --------------------------------------------------------------------------- per-strategy review
+
+@dataclass
+class StrategyReview:
+    """One strategy's retrospective review. Every unavailable input is LOUD (a reason string), never
+    a confident default; the two field-proven defects are killed by construction (see module docstring)."""
+
+    strategy: str
+    wallet: Optional[str] = None
+    runtime_id: Optional[str] = None
+    thesis: Optional[str] = None
+
+    # history (backend trade history)
+    history_available: bool = True
+    history_reason: str = ""
+    closed_trade_count: int = 0
+    wins: int = 0
+    losses: int = 0
+    flats: int = 0
+    realized_pnl: float = 0.0
+
+    # exit enrichment (box event log)
+    events_available: bool = False
+    events_reason: str = ""
+    exit_distribution: dict = field(default_factory=dict)   # terminal -> count (attributed exits)
+    exits_unknown: int = 0                                   # closed trades with no matched exit event
+    premature_exits: int = 0
+    leaks: dict = field(default_factory=dict)               # {order_failed, protection_gaps, risk_halts}
+
+    recommendations: list[str] = field(default_factory=list)
+
+    @property
+    def win_rate(self) -> Optional[float]:
+        decided = self.wins + self.losses
+        return round(self.wins / decided, 4) if decided else None
+
+    @property
+    def no_closed_trades(self) -> bool:
+        """The HONEST empty state — history read fine, but nothing closed. NOT telemetry-unavailable
+        (the defect this verb kills): a strategy waiting for its signal simply has nothing to review."""
+        return self.history_available and self.closed_trade_count == 0
+
+    def _leak_total(self) -> int:
+        return sum(int((self.leaks.get(k) or {}).get("count", 0)) for k in self.leaks)
+
+    def to_json(self) -> dict:
+        return {
+            "strategy": self.strategy,
+            "wallet": self.wallet,
+            "runtime_id": self.runtime_id,
+            "thesis": self.thesis,
+            "sources": {"history": SRC_HISTORY, "events": SRC_EVENTS},
+            "history": {
+                "available": self.history_available,
+                "reason": self.history_reason,
+                "closed_trade_count": self.closed_trade_count,
+                "wins": self.wins,
+                "losses": self.losses,
+                "flats": self.flats,
+                "win_rate": self.win_rate,
+                "realized_pnl": self.realized_pnl,
+            },
+            "events": {
+                "available": self.events_available,
+                "reason": self.events_reason,
+                "exit_distribution": dict(self.exit_distribution),
+                "exits_unknown": self.exits_unknown,
+                "premature_exits": self.premature_exits,
+                "leaks": {k: {"count": (v or {}).get("count", 0),
+                              "samples": list((v or {}).get("samples", []))}
+                          for k, v in self.leaks.items()},
+            },
+            "recommendations": list(self.recommendations),
+        }
+
+    def render(self) -> list[str]:
+        lines = [f"  {self.strategy}"]
+        if self.wallet:
+            lines.append(f"    wallet     : {self.wallet}")
+        if self.thesis:
+            lines.append(f'    thesis     : "{self.thesis}"  (quoted from the graph)')
+        # HISTORY (backend trade history) — LOUD when unavailable; the honest empty when nothing closed.
+        if not self.history_available:
+            lines.append(f"    trades     : UNAVAILABLE ({self.history_reason}) [{SRC_HISTORY}] "
+                         f"— NOT assuming zero")
+            return lines
+        if self.closed_trade_count == 0:
+            lines.append("    trades     : no closed trades yet — nothing to review "
+                         "(often by design: waiting for its signal, not a defect)")
+            return lines
+        wr = self.win_rate
+        wr_s = f"{wr * 100:.0f}%" if wr is not None else "n/a"
+        lines.append(f"    trades     : {self.closed_trade_count} closed — "
+                     f"{self.wins}W / {self.losses}L / {self.flats} flat, win rate {wr_s}, "
+                     f"realized PnL ${self.realized_pnl:,.2f}  [{SRC_HISTORY}]")
+        # EXITS + leaks (box event log) — undetermined ≠ all-clear when the ring is unavailable.
+        if not self.events_available:
+            lines.append(f"    exits      : UNDETERMINED ({self.events_reason}) [{SRC_EVENTS}] "
+                         f"— exit quality / leaks couldn't be checked, NOT 'clean'")
+        else:
+            if self.exit_distribution:
+                mix = ", ".join(f"{k}×{v}" for k, v in sorted(self.exit_distribution.items()))
+                lines.append(f"    exits      : {mix}"
+                             + (f", unknown×{self.exits_unknown}" if self.exits_unknown else "")
+                             + f"  [{SRC_EVENTS}]")
+            else:
+                lines.append(f"    exits      : no exit events matched these trades "
+                             f"(unknown×{self.exits_unknown})  [{SRC_EVENTS}]")
+            if self.premature_exits:
+                lines.append(f"    premature  : {self.premature_exits} exit(s) look premature "
+                             f"(trailing_floor / weak_peak / low-tier lock)")
+            leak_total = self._leak_total()
+            if leak_total:
+                parts = []
+                for key, label in (("order_failed", "failed order(s)"),
+                                   ("protection_gaps", "protection-sync gap(s)"),
+                                   ("risk_halts", "risk halt(s)")):
+                    c = int((self.leaks.get(key) or {}).get("count", 0))
+                    if c:
+                        parts.append(f"{c} {label}")
+                lines.append(f"    leaks      : {', '.join(parts)}  [{SRC_EVENTS}]")
+            else:
+                lines.append(f"    leaks      : none recorded  [{SRC_EVENTS}]")
+        for r in self.recommendations:
+            lines.append(f"    → {r}")
+        return lines
+
+
+def _events_for_runtime(section: Optional[dict], runtime_id: Optional[str]) -> tuple[Optional[list], str]:
+    """Resolve one strategy's event ring from the live document's ``events`` section. Returns
+    ``(rows | None, reason)``: rows (possibly empty = a genuine empty ring) when available; None + a
+    LOUD reason otherwise. The reason paths are DISTINCT so 'no live channel' never masquerades as
+    'the ring is empty' (the defect-2 discipline: nothing-to-enrich ≠ telemetry-down)."""
+    if section is None:
+        return None, "no live channel — run via the rim (events are served in-process there)"
+    if section.get("ok") is False:
+        return None, section.get("reason") or "events channel unavailable"
+    if not runtime_id:
+        return None, "strategy has no installed runtime on this box — no event ring"
+    by_runtime = section.get("by_runtime")
+    if not isinstance(by_runtime, dict) or runtime_id not in by_runtime:
+        return None, f"no event ring fetched for runtime {runtime_id!r} (per-ring read failed)"
+    rows = by_runtime.get(runtime_id)
+    return ([r for r in rows if isinstance(r, dict)] if isinstance(rows, list) else []), ""
+
+
+def _recommend(sr: StrategyReview) -> list[str]:
+    """Plain, DERIVED recommendations — NO ML, NO scoring. Each is a factual routing of an observed
+    count to the lever that addresses it; when exits are undetermined the exit-quality read is called
+    out as UNCHECKED (never 'clean'), and a thesis (when present) frames the realized outcome."""
+    recs: list[str] = []
+    if not sr.history_available or sr.closed_trade_count == 0:
+        return recs
+    if sr.events_available:
+        if sr.premature_exits:
+            recs.append(f"{sr.premature_exits} exit(s) look premature — consider widening the DSL "
+                        f"phase-1 retrace or retuning the arming tier so a working position isn't cut early.")
+        for key, msg in (
+            ("order_failed", "failed order(s) — $ never entered; check sizing / margin / the reject reason."),
+            ("protection_gaps", "protection-sync gap(s) — a stop couldn't sync/hand off (naked-leg risk); "
+                                "check the exchange stop binding."),
+            ("risk_halts", "risk halt(s) — trading was paused; review the halt reason vs the risk gates."),
+        ):
+            c = int((sr.leaks.get(key) or {}).get("count", 0))
+            if c:
+                recs.append(f"{c} {msg}")
+    else:
+        recs.append("exit quality + leaks are UNDETERMINED (the box event ring was unavailable) — "
+                    "re-run via the rim to enrich; do NOT read the absence as 'clean'.")
+    wr = sr.win_rate
+    if sr.realized_pnl < 0 and wr is not None and wr < 0.5:
+        recs.append(f"net realized LOSS (${sr.realized_pnl:,.2f}) at a {wr * 100:.0f}% win rate over "
+                    f"{sr.closed_trade_count} trade(s)"
+                    + (f' — judge it against the thesis: "{sr.thesis}".' if sr.thesis
+                       else " — no thesis on the graph to judge against."))
+    return recs
+
+
+def _review_one(base_state_dir: str, strategy: str, runtime_id: Optional[str], wallet: Optional[str],
+                history_fn: HistoryFn, events_section: Optional[dict]) -> StrategyReview:
+    """Review ONE strategy. Fail-open per input: a history transport failure marks history unavailable
+    (LOUD) and returns; an unavailable event ring marks exits undetermined; zero closed trades is the
+    honest empty. Never raises (the sweep must survive one bad strategy)."""
+    sr = StrategyReview(strategy=strategy, wallet=wallet, runtime_id=runtime_id,
+                        thesis=_read_thesis(base_state_dir, strategy))
+
+    # HISTORY — backend trade history via the injected seam. Unavailable is LOUD, never a fake zero.
+    if not wallet:
+        sr.history_available = False
+        sr.history_reason = "no wallet bound to this strategy (not funded/installed yet)"
+        return sr
+    try:
+        rows = history_fn(wallet)
+    except HistoryUnavailable as e:
+        sr.history_available = False
+        sr.history_reason = str(e)
+        return sr
+    except Exception as e:  # noqa: BLE001 — a surprise seam fault is a per-strategy datum
+        sr.history_available = False
+        sr.history_reason = f"history read raised ({e})"
+        return sr
+
+    trades = _parse_closed_trades(rows)
+    sr.closed_trade_count = len(trades)
+    sr.realized_pnl = round(sum(_num(t.get("realized_pnl")) or 0.0 for t in trades), 2)
+    for t in trades:
+        pnl = _num(t.get("realized_pnl")) or 0.0
+        if pnl > 0:
+            sr.wins += 1
+        elif pnl < 0:
+            sr.losses += 1
+        else:
+            sr.flats += 1
+
+    # EXIT enrichment — box event log ONLY (the hard rule: no events subprocess fallback). The ring
+    # is fetched even with zero closed trades so its leaks still count, but exit attribution only runs
+    # over trades. An unavailable ring => exits UNDETERMINED (never conflated with 'no closed trades').
+    rows_ev, reason = _events_for_runtime(events_section, runtime_id)
+    if rows_ev is None:
+        sr.events_available = False
+        sr.events_reason = reason
+    else:
+        sr.events_available = True
+        sr.leaks = _scan_leaks(rows_ev)
+        if trades:
+            by_order_id, by_asset = _index_exit_events(rows_ev)
+            dist: dict = {}
+            for t in trades:
+                ev = _match_exit_event(t, by_order_id, by_asset)
+                if ev is None:
+                    sr.exits_unknown += 1
+                    continue
+                er = _exit_reason_from_event(ev)
+                terminal = str(er.get("terminal") or "unknown") or "unknown"
+                dist[terminal] = dist.get(terminal, 0) + 1
+                if _is_premature_exit(er):
+                    sr.premature_exits += 1
+            sr.exit_distribution = dist
+
+    sr.recommendations = _recommend(sr)
+    return sr
+
+
+# --------------------------------------------------------------------------- review result
+
+@dataclass
+class ReviewResult:
+    base_state_dir: str
+    scope: str                                        # "all" (sweep) | "strategy" (targeted)
+    strategies: list[StrategyReview] = field(default_factory=list)
+
+    # cross-strategy realized aggregate (the realized-PnL/history view the retired portfolio skill
+    # left un-homed). Sums ONLY strategies whose history was READABLE (unreadable ones are a FLOOR,
+    # not a hole silently counted as zero).
+    def _readable(self) -> list[StrategyReview]:
+        return [s for s in self.strategies if s.history_available]
+
+    @property
+    def total_closed(self) -> int:
+        return sum(s.closed_trade_count for s in self._readable())
+
+    @property
+    def total_realized(self) -> float:
+        return round(sum(s.realized_pnl for s in self._readable()), 2)
+
+    @property
+    def total_wins(self) -> int:
+        return sum(s.wins for s in self._readable())
+
+    @property
+    def total_losses(self) -> int:
+        return sum(s.losses for s in self._readable())
+
+    @property
+    def overall_win_rate(self) -> Optional[float]:
+        decided = self.total_wins + self.total_losses
+        return round(self.total_wins / decided, 4) if decided else None
+
+    @property
+    def history_partial(self) -> bool:
+        return len(self._readable()) < len(self.strategies)
+
+    def to_json(self) -> dict:
+        return {
+            "verb": "review",
+            "scope": self.scope,
+            "state_dir": self.base_state_dir,
+            "sources": {"history": SRC_HISTORY, "events": SRC_EVENTS},
+            "strategy_count": len(self.strategies),
+            "strategies": [s.to_json() for s in self.strategies],
+            "aggregate": {
+                "total_closed_trades": self.total_closed,
+                "total_realized_pnl": self.total_realized,
+                "wins": self.total_wins,
+                "losses": self.total_losses,
+                "overall_win_rate": self.overall_win_rate,
+                "history_partial": self.history_partial,
+            },
+        }
+
+    def render(self) -> str:
+        lines = [
+            f"trade review  (state: {self.base_state_dir})",
+            f"realized PnL + win rate quoted from {SRC_HISTORY}; exit reasons + leaks from the "
+            f"{SRC_EVENTS}. Unavailable inputs are shown as such, never assumed.",
+            "",
+            f"strategies ({len(self.strategies)}):",
+        ]
+        if not self.strategies:
+            lines.append("  (none — no strategy under <state>/composer or a landed <state>/strategies "
+                         "install)")
+        for s in self.strategies:
+            lines.extend(s.render())
+        # cross-strategy realized aggregate (only meaningful on the sweep with readable history).
+        if len(self.strategies) > 1:
+            lines.append("")
+            wr = self.overall_win_rate
+            wr_s = f"{wr * 100:.0f}%" if wr is not None else "n/a"
+            floor = " (FLOOR — some strategies' history was unavailable)" if self.history_partial else ""
+            lines.append(f"cross-strategy realized aggregate{floor}:")
+            lines.append(f"  {self.total_closed} closed trade(s), "
+                         f"{self.total_wins}W / {self.total_losses}L, overall win rate {wr_s}, "
+                         f"total realized PnL ${self.total_realized:,.2f}  [{SRC_HISTORY}]")
+        return "\n".join(lines) + "\n"
+
+
+# --------------------------------------------------------------------------- entry point
+
+def _noop_state_fn(_runtime_id: Optional[str]) -> LiveState:
+    """The SystemStateFn review hands run_status: review does NOT read live DSL/scanner state (it is a
+    retrospective realized review, not a live snapshot), so this returns an unavailable marker rather
+    than let run_status fall back to a `senpi state` cold boot. Honors the hard no-cold-boot rule."""
+    return LiveState(False, reason="not read (review does not read live state)")
+
+
+def run_review(
+    base_state_dir: str,
+    target: Optional[str] = None,
+    *,
+    history_fn: HistoryFn = default_closed_history,
+    events_fn: EventsFn = default_events_section,
+    list_fn=_box.default_list_runtimes,
+) -> ReviewResult:
+    """Retrospective trade-quality review. Bare (``target`` None) sweeps every accountable strategy
+    (canonical + landed-legacy, via ``portfolio.enumerate_strategies``) + the cross-strategy realized
+    aggregate; a named target reviews that ONE strategy. Each strategy's on-box runtime id + wallet
+    are derived by the SINGLE PRODUCER (``run_status`` + ``portfolio._effective_install``), reusing the
+    rim-served ``runtime_list`` (no cold boot) and the no-op state_fn (no live-state read). Closed
+    history comes from ``history_fn`` (in-process MCP seam); exit/leak enrichment from ``events_fn``
+    (the live document's ``events`` section — NEVER a subprocess). Fail-open per strategy."""
+    state_dir = Path(base_state_dir)
+    result = ReviewResult(base_state_dir=str(state_dir),
+                          scope="strategy" if target else "all")
+
+    if target:
+        names = [target]
+    else:
+        names = enumerate_strategies(state_dir)
+
+    # ONE runtime-list read shared across the sweep (served from the live doc; empty-on-error).
+    try:
+        runtimes = list_fn()
+    except Exception:  # noqa: BLE001 — a listing fault degrades to no runtime ids, not a crash
+        runtimes = []
+    shared_list = lambda: runtimes  # noqa: E731
+
+    # the events section is read ONCE (the whole live document is served once per invocation).
+    try:
+        events_section = events_fn()
+    except Exception:  # noqa: BLE001 — an events-read fault degrades to unavailable, not a crash
+        events_section = None
+
+    for strategy in names:
+        st = run_status(strategy, state_dir=str(state_dir),
+                        list_fn=shared_list, state_fn=_noop_state_fn)
+        install = _effective_install(st)
+        runtime_id = install.runtime_id if install is not None else None
+        wallet = _resolve_wallet(state_dir, strategy, install)
+        result.strategies.append(
+            _review_one(str(state_dir), strategy, runtime_id, wallet, history_fn, events_section))
+    return result