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

package/dist/composer/authoring/archetypes/relative_value.py

@@ -8,9 +8,12 @@ whose benchmark leg is pinned in the universe (never discovered, never held/dedu
 narrowing could prune the benchmark and silently break the comparison) and whose cross-asset
 comparison lives in ONE two-output signed-net-score pure_fn (D2 kind 2).
 
-This builder builds the PAIRWISE member first (design-models §11: `relative_value.pairwise`,
-with `cross_sectional` — long the strongest vs short the weakest of N — the designed
-follow-up member). One pure_fn produces BOTH tails from the same signed net score:
+This module builds BOTH members of the family (design-models §11), dispatched by `build()` from
+the universe ingredients (no member field): `relative_value.pairwise` (this file's first half — the
+fixed [target, benchmark] two-asset compare, when the whitelist is EXACTLY two) and
+`relative_value.cross_sectional` (the second half, below — long the strongest vs fade the weakest of
+N, when the whitelist has >= 3 names or the board is discovered). The pairwise builder's one pure_fn
+produces BOTH tails from the same signed net score:
 
   * entry_scores — LONG the target when the benchmark has out-returned it (target is
     relatively cheap) by net >= enter_threshold AND the target is NOT already held.
@@ -45,6 +48,7 @@ from __future__ import annotations
 
 from ..answers import Answers
 from ..builder import GraphBuilder
+from . import _common
 from ._common import GenerationError
 
 DESCRIBE = [
@@ -72,8 +76,11 @@ DESCRIBE = [
     "the incident that motivated the family). If the signal is one asset's own trend/momentum in",
     "isolation, it is trend_momentum.",
     "",
-    "Members: `pairwise` (this builder — the fixed two-asset pair) is the first; `cross_sectional`",
-    "(long the strongest vs short the weakest across N names) is the designed follow-up.",
+    "Members (inferred from the universe — no member field): `pairwise` = EXACTLY two whitelisted",
+    "assets [target, benchmark] (the fixed two-asset compare); `cross_sectional` = a whitelist of",
+    ">= 3 names OR a discovered board — rank the universe by relative strength, LONG the strongest",
+    "and SHORT (fade) the weakest within slot caps (the `rotation` cluster; enter_threshold/",
+    "exit_threshold become the relative-strength ENTER band and the CONVERGENCE exit band).",
     "",
     "Emits: clearinghouse_state (equity for sizing — NO held-exclusion on the entry universe),",
     "open_positions (held + direction, for in-fn held-exclusion and the exit direction stamp),",
@@ -81,7 +88,7 @@ DESCRIBE = [
     "TWO outputs), emit_single_best + signal_envelope (entry tail), and close_signal_envelope",
     "(exit tail — only when exit_signals is set).",
     "",
-    "Answers that matter: universe.whitelist = [target, benchmark] (EXACTLY two — no discover),",
+    "Answers that matter (pairwise): universe.whitelist = [target, benchmark] (EXACTLY two);",
     "intervals (the candle interval + window bar counts), exit_signals.{enter_threshold,",
     "exit_threshold, interval_seconds, reentry_cooldown_seconds, min_divergence} (present => the",
     "exit tail; min_divergence is the per-window vote NOISE GATE threaded into the scoring pure_fn —",
@@ -233,28 +240,38 @@ def _relative_value_tests(
 
 
 def build(answers: Answers) -> GraphBuilder:
+    """Dispatch the relative_value FAMILY to its member (taxonomy: family = thesis shape, members =
+    ingredient combos). The MEMBER is inferred from the universe INGREDIENTS (the least-new-surface
+    convention — no member field):
+
+      * ``pairwise`` — EXACTLY two whitelisted assets, no discovery: the fixed [target, benchmark]
+        cross-asset compare (the original member).
+      * ``cross_sectional`` — a DISCOVERED board OR a whitelist of >= 3 names: rank the universe by
+        relative strength, LONG the strongest / SHORT (fade) the weakest within slot caps.
+
+    A whitelist of 0 or 1 (with no discovery) fits neither and is rejected LOUDLY."""
+    u = answers.universe
+    if u.discover or len(u.whitelist) >= 3:
+        return _build_cross_sectional(answers)
+    if len(u.whitelist) != 2:
+        raise GenerationError(
+            "archetype 'relative_value' needs EITHER exactly two whitelisted assets as [target, "
+            f"benchmark] (the pairwise member) OR a discovered board / a whitelist of >= 3 names "
+            f"(the cross_sectional member); got universe.whitelist={list(u.whitelist)} with "
+            f"discover={u.discover}. The pairwise FIRST asset is the traded target, the SECOND is "
+            "the reference benchmark (never traded)."
+        )
+    return _build_pairwise(answers)
+
+
+def _build_pairwise(answers: Answers) -> GraphBuilder:
     b = GraphBuilder()
     u = answers.universe
     iv = answers.intervals[0] if answers.intervals else "4h"
 
-    # relative_value.pairwise is a FIXED-PAIR shape: no discovery (that would prune the benchmark
-    # from a live-board narrowing) and EXACTLY two assets. Reject anything else LOUDLY rather than
-    # silently emit a broken universe (mirrors trend_momentum's discover guard).
-    if u.discover:
-        raise GenerationError(
-            "archetype 'relative_value' (pairwise member) is a FIXED-PAIR shape and cannot "
-            "discover a universe from the live board — discovery could prune the benchmark leg. "
-            "Set universe.whitelist to exactly [target, benchmark]. (A discovered cross-sectional "
-            "long-strongest/short-weakest variant is the designed cross_sectional follow-up member, "
-            "not yet built.)"
-        )
+    # relative_value.pairwise is a FIXED-PAIR shape: EXACTLY two assets, no discovery (the dispatcher
+    # guarantees this — a discovered/>=3 universe routes to cross_sectional).
     pair = list(u.whitelist)
-    if len(pair) != 2:
-        raise GenerationError(
-            "archetype 'relative_value' (pairwise member) needs EXACTLY two assets in "
-            f"universe.whitelist as [target, benchmark]; got {pair}. The FIRST is the traded "
-            "target, the SECOND is the reference benchmark (never traded)."
-        )
     target, benchmark = pair[0], pair[1]
 
     bars = _BARS_PER_DAY.get(iv)
@@ -374,3 +391,243 @@ def build(answers: Answers) -> GraphBuilder:
                   section="exit tail: exit_scores -> close emitter (+ positions for direction)")
         b.connect("positions", "positions", "close_emit", "positions")
     return b
+
+
+# --------------------------------------------------------------------------- cross_sectional member
+#
+# The `cross_sectional` member (design-models §11; capability-regression audit §E4) — the
+# designed-but-unbuilt follow-up: rank a UNIVERSE (a fixed basket of >= 3 OR a discovered board) by
+# RELATIVE STRENGTH and go LONG the strongest / SHORT (fade) the weakest, capped to the open slots.
+# It covers the `rotation` corpus cluster (sailfish long-only single-best; lion / gibbon / orangutan
+# / wolf long/short rank-and-ride). It reuses the relative_value family's conventions verbatim: the
+# same 3d/7d/30d lookback windows + weights (WINDOWS), the same days->bars mapping (_BARS_PER_DAY),
+# the same two-output pure_fn shape with in-fn held-exclusion, and the SAME exit_signals surface
+# (enter_threshold/exit_threshold are the relative-strength ENTER band and the CONVERGENCE exit band).
+#
+# The RANKER CONSTRAINT (handover 2026-07-19 tripwire: 2 fixed rankers, no pure_fn-shaped ranking
+# hatch): a cross-sectional long/short is expressed WITHIN the existing rankers by having the pure_fn
+# score BOTH tails by |relative strength| and stamp the direction per score_map entry — the ranker
+# then caps to the top-N by magnitude (a mix of strongest-longs + weakest-shorts), no new ranker
+# type. max_positions drives single-best (the single strongest, sailfish) vs pool-cap (lion/gibbon).
+
+# The cross-sectional relative-strength scorer (D2 kind 2). Generic over the bound windows/weights/
+# thresholds (all passed as params); emitted verbatim AND executed in _cross_sectional_tests.
+CROSS_SECTIONAL_FN = '''\
+def score_cross_sectional(ret_3d, ret_7d, ret_30d, positions, enter_threshold, exit_threshold, w_3d, w_7d, w_30d, signal_strength):
+    # TODO(edit): the CROSS-SECTIONAL relative-strength edge (a WORKING DEFAULT; the `rotation`
+    # cluster — sailfish/lion/gibbon). For each asset the COMPOSITE momentum is the WEIGHTED AVERAGE
+    # of its 3d/7d/30d returns (a longer window is a more durable read, so it carries more weight).
+    # RELATIVE STRENGTH is composite minus the CROSS-SECTIONAL MEAN composite across the universe.
+    # ENTER when FLAT: LONG the strongest (RS >= enter_threshold), SHORT (fade) the weakest
+    # (RS <= -enter_threshold); between the bands is the dead band (emit nothing). EXIT a HELD name
+    # when its relative value has CONVERGED (|RS| <= exit_threshold — the spread the trade was betting
+    # on has closed) OR its RS has FLIPPED sign (it rotated to the other tail). Both tails score by
+    # |RS| so the fixed ranker caps to the top-N by magnitude. Held-exclusion + the real held direction
+    # live here (via positions) so entry and exit never both fire. A window missing a leg abstains; an
+    # empty universe returns nothing, never raises. Encode YOUR edge by editing this body — it is
+    # purity-checked (no ctx/MCP/I/O, math only) and its inline tests run at validate time.
+    composite = {}
+    for asset in sorted(set(ret_3d) | set(ret_7d) | set(ret_30d)):
+        acc = 0.0
+        wsum = 0.0
+        for series, weight in ((ret_3d, w_3d), (ret_7d, w_7d), (ret_30d, w_30d)):
+            value = series.get(asset)
+            if value is None:
+                continue
+            acc = acc + value * weight
+            wsum = wsum + weight
+        if wsum <= 0.0:
+            continue
+        composite[asset] = acc / wsum
+    if not composite:
+        return {}, {}
+    mean = sum(composite.values()) / len(composite)
+    held = {}
+    for record in positions or []:
+        coin = str(record.get("coin", "")).upper()
+        if coin:
+            held[coin] = record.get("direction") or "LONG"
+    entry_scores = {}
+    exit_scores = {}
+    for asset in sorted(composite):
+        rs = composite[asset] - mean
+        held_direction = held.get(str(asset).upper())
+        if held_direction is None:
+            if rs >= enter_threshold:
+                entry_scores[asset] = {"score": round(signal_strength * rs, 4), "direction": "LONG",
+                                       "reasons": ["relative_strength"]}
+            elif rs <= -enter_threshold:
+                entry_scores[asset] = {"score": round(signal_strength * abs(rs), 4), "direction": "SHORT",
+                                       "reasons": ["relative_weakness"]}
+        else:
+            converged = abs(rs) <= exit_threshold
+            flipped = (held_direction == "LONG" and rs < 0.0) or (held_direction == "SHORT" and rs > 0.0)
+            if converged or flipped:
+                exit_scores[asset] = {"score": round(abs(rs), 4), "direction": held_direction,
+                                      "reasons": ["converged" if converged else "rank_flip"]}
+    return entry_scores, exit_scores
+'''
+
+
+def _cross_sectional_tests(
+    weights: tuple[float, ...], enter: float, exit_threshold: float,
+) -> tuple[dict, ...]:
+    """Six inline fixtures whose expected values are computed from the default body itself with the
+    BOUND weights/thresholds, so they pass by construction. Semantic cases: long-strongest entry,
+    short-weakest entry, dead band, converged exit (held), rank-flip exit (held), flat-no-exit. Each
+    window carries the same per-asset value so composite == that value (keeps the arithmetic legible)."""
+    fn = _exec_fn(CROSS_SECTIONAL_FN)
+    w3, w7, w30 = weights
+
+    def call(series, positions):
+        e, x = fn(series, series, series, positions, enter, exit_threshold, w3, w7, w30, _SIGNAL_STRENGTH)
+        return {"entry_scores": e, "exit_scores": x}
+
+    # values chosen so the cross-sectional mean is 0 and RS = the raw value:
+    strong = enter + 5.0     # clearly the strongest (LONG)
+    weak = -(enter + 5.0)    # clearly the weakest (SHORT)
+    spread = {"AAA": strong, "BBB": 0.0, "CCC": weak}          # mean 0; AAA long, CCC short, BBB dead
+    tight = {"AAA": exit_threshold / 2.0, "BBB": 0.0, "CCC": -exit_threshold / 2.0}  # all within bands
+    held_long_aaa = [{"coin": "AAA", "direction": "LONG", "szi": 1.0,
+                      "entry_px": 100.0, "unrealized_pnl_pct": 2.0, "margin_used": 10.0}]
+    # a held LONG on the now-WEAKEST name (RS flipped negative) -> rank_flip exit.
+    flip = {"AAA": weak, "BBB": 0.0, "CCC": strong}
+
+    cases = (
+        ("long_strongest_entry", spread, []),
+        ("short_weakest_entry", spread, []),        # same input; asserts CCC SHORT is present
+        ("dead_band_emits_nothing", tight, []),
+        ("converged_exit_when_held", tight, held_long_aaa),
+        ("rank_flip_exit_when_held", flip, held_long_aaa),
+        ("flat_no_exit", tight, []),
+    )
+    return tuple(
+        {"name": name, "inputs": {"ret_3d": s, "ret_7d": s, "ret_30d": s, "positions": pos},
+         "expect": call(s, pos)}
+        for name, s, pos in cases
+    )
+
+
+def _build_cross_sectional(answers: Answers) -> GraphBuilder:
+    b = GraphBuilder()
+    u = answers.universe
+    iv = answers.intervals[0] if answers.intervals else "4h"
+
+    bars = _BARS_PER_DAY.get(iv)
+    if bars is None:
+        raise GenerationError(
+            f"archetype 'relative_value' (cross_sectional member) cannot map interval {iv!r} to a "
+            f"bars-per-day count (supported: {sorted(_BARS_PER_DAY)}). Choose a standard candle "
+            f"interval so the lookback windows (3d/7d/30d) resolve to bar counts."
+        )
+
+    es = answers.exit_signals
+    enter_threshold = es.enter_threshold if es is not None else _DEFAULT_ENTER
+    exit_threshold = es.exit_threshold if es is not None else _DEFAULT_EXIT
+    weights = tuple(w for _d, w in WINDOWS)
+
+    # --- sources ---
+    b.add("account", "clearinghouse_state",
+          header=("sources: account equity for sizing. NO held-exclusion on the ranked universe —",
+                  "held-exclusion lives in the pure_fn (enter only when flat, exit only when held).",))
+    b.add("positions", "open_positions",
+          header=("open positions (held + direction): in-fn held-exclusion + the exit tail's REAL",
+                  "held-direction stamp. Kept even in the entry-only variant (no-pyramiding).",))
+
+    # --- universe: a fixed basket (>= 3) OR a discovered board ---
+    if u.discover:
+        b.add("board", "instrument_list", {"dex": u.dex},
+              header=("dynamic universe discovery: live board -> leverage/volume/prefix signature.",))
+        b.add("universe", "universe_discover",
+              {"name_prefix": u.name_prefix, "max_leverage_cap": u.max_leverage_cap,
+               "min_day_volume": u.min_day_volume})
+        b.add("candles", "candles_fetch", {"intervals": [iv]},
+              header=("candle reads over the discovered universe (ranked cross-sectionally).",))
+    else:
+        b.add("candles", "candles_fetch",
+              {"whitelist": list(u.whitelist), "intervals": [iv]},
+              header=("candle reads over the fixed basket (ranked cross-sectionally).",))
+
+    # --- N lookback returns (days -> bars at the chosen interval), each a per-asset feature_map ---
+    window_ids: list[str] = []
+    for i, (days, _weight) in enumerate(WINDOWS):
+        wid = f"ret_{days}d"
+        b.add(wid, "pct_change", {"lookback": days * bars, "interval": iv},
+              header=(f"lookback returns at {iv} ({days}d = {days * bars} x {iv}).",) if i == 0 else ())
+        window_ids.append(wid)
+
+    # --- the two-output cross-sectional relative-strength scorer (THE EDGE slot; D2 kind 2) ---
+    b.add_pure_fn(
+        "score",
+        inputs=tuple(
+            {"name": wid, "type": "feature_map",
+             "doc": f"Per-asset {days}d ({days * bars} x {iv}) percent return."}
+            for wid, (days, _w) in zip(window_ids, WINDOWS)
+        ) + (
+            {"name": "positions", "type": "record_list",
+             "doc": "Open positions (from open_positions) — held-exclusion + exit direction."},
+        ),
+        outputs=(
+            {"name": "entry_scores", "type": "score_map",
+             "doc": "LONG the strongest (RS >= enter_threshold) / SHORT the weakest (RS <= -enter_threshold), FLAT."},
+            {"name": "exit_scores", "type": "score_map",
+             "doc": "CLOSE a held name whose |RS| converged below exit_threshold OR whose RS flipped sign."},
+        ),
+        params=(
+            {"name": "enter_threshold", "type": "float", "default": enter_threshold,
+             "doc": "Relative strength to ENTER (top of the dead band); |RS| in return-percent units."},
+            {"name": "exit_threshold", "type": "float", "default": exit_threshold,
+             "doc": "Convergence band; a held name whose |RS| falls below it CLOSES (relative value realized)."},
+            {"name": "w_3d", "type": "float", "default": weights[0], "doc": "Weight of the 3d window."},
+            {"name": "w_7d", "type": "float", "default": weights[1],
+             "doc": "Weight of the 7d window (longer = stronger)."},
+            {"name": "w_30d", "type": "float", "default": weights[2],
+             "doc": "Weight of the 30d window (longest = strongest)."},
+            {"name": "signal_strength", "type": "float", "default": _SIGNAL_STRENGTH,
+             "doc": "Per-signal score unit multiplier."},
+        ),
+        fn=CROSS_SECTIONAL_FN,
+        tests=_cross_sectional_tests(weights, enter_threshold, exit_threshold),
+        header=("pure_fn cross-sectional relative-strength scorer — THE EDGE SLOT (edit the body; see",
+                "the EDGE block above). TWO outputs: entry_scores (long strong / short weak) + exit_scores.",),
+        title="cross-sectional relative strength: long the strongest, fade the weakest",
+    )
+    b.set_edge_anchor("score")
+
+    # --- entry tail: ranker (single-best = the single strongest, or pool-cap) -> emitter ---
+    _common.add_ranker(
+        b, ranker_id="best", scorer_id="score", scorer_port="entry_scores",
+        account_id="account", max_positions=answers.max_positions,
+    )
+    b.add("emit", "signal_envelope",
+          {"margin_pct": answers.risk.margin_pct, "leverage": answers.risk.leverage},
+          header=("entry emitter: build the scan() OPEN signal list.",))
+
+    # --- exit tail: only when a thesis (convergence) exit was requested (answers.exit_signals) ---
+    if es is not None:
+        b.add("close_emit", "close_signal_envelope", {"signal_type": "thesis_exit"},
+              header=("exit emitter: reduce-only CLOSE list (no sizing/equity). The compiler splits",
+                      "this into a second, exit-only scanner; the DSL preset stays as the safety net.",))
+
+    # --- edges ---
+    if u.discover:
+        b.connect("board", "instruments", "universe", "instruments", section="dynamic universe discovery")
+        b.connect("universe", "universe", "candles", "assets", section="discovered universe -> candle reads")
+    # candles fan out to the lookback returns
+    for i, wid in enumerate(window_ids):
+        b.connect("candles", "candles", wid, "candles",
+                  section="candles fan out to the lookback returns" if i == 0 else None)
+    # each return + the positions record wire into ONE declared pure_fn input (single writer)
+    for i, wid in enumerate(window_ids):
+        b.connect(wid, "pct", "score", wid,
+                  section="each lookback return -> its pure_fn input port" if i == 0 else None)
+    b.connect("positions", "positions", "score", "positions")
+    # entry tail: entry_scores -> rank (wired inside add_ranker) -> emit (+ equity for sizing)
+    b.connect("best", "selected", "emit", "selected", section="entry tail: entry_scores -> rank -> emit")
+    b.connect("account", "equity", "emit", "equity")
+    # exit tail: exit_scores -> close emitter (+ positions for the real held-direction stamp)
+    if es is not None:
+        b.connect("score", "exit_scores", "close_emit", "selected",
+                  section="exit tail: exit_scores -> close emitter (+ positions for direction)")
+        b.connect("positions", "positions", "close_emit", "positions")
+    return b

package/dist/composer/cli.py

@@ -65,10 +65,13 @@ from composer.verbs import (
     run_group_close,
     run_group_status,
     run_install,
+    run_portfolio_status,
+    run_review,
     run_simulate,
     run_status,
     run_update,
 )
+from composer.verbs._box import default_read_positions
 from composer.verbs._layout import (
     canonical_graph_path,
     canonical_staged_dir,
@@ -506,6 +509,7 @@ def _cmd_fund(args: argparse.Namespace) -> int:
         _resolve_state_dir(args.state_dir),
         out_dir=args.out,
         created_at=args.created_at,
+        manual=args.manual,
     )
     if args.json:
         print(json.dumps(result.to_json(), indent=2, sort_keys=True))
@@ -580,13 +584,37 @@ def _cmd_status(args: argparse.Namespace) -> int:
         return 0
 
     if args.target is None:
-        print("status needs a target (a graph file / staging dir / strategy name) or --group <name>.",
-              file=sys.stderr)
-        return 1
+        # J2: bare `status` (no target, no --group) is the CROSS-STRATEGY PORTFOLIO view — every
+        # accountable strategy + stranded runtimes + manual positions. It is inherently on-box, so it
+        # RESOLVES the state root (CMP248 if unresolvable — the rim always threads it). The targeted
+        # per-strategy path below is byte-unchanged.
+        result = run_portfolio_status(_resolve_state_dir(args.state_dir))
+        if args.json:
+            print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+        else:
+            print(result.render(), end="")
+        return 0
     # --state-dir opts INTO the on-box install-chain derivation; without it status stops at the
-    # deploy layer (the file-only lifecycle), exactly as before.
+    # deploy layer (the file-only lifecycle), exactly as before. J3: wire the clearinghouse seam so a
+    # MANUAL strategy's wallet positions render (managed status never invokes it — manual-branch only).
     state_dir = _resolve_state_dir(args.state_dir) if args.state_dir is not None else None
-    result = run_status(args.target, out_dir=args.out, state_dir=state_dir)
+    result = run_status(args.target, out_dir=args.out, state_dir=state_dir,
+                        positions_fn=default_read_positions)
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0
+
+
+def _cmd_review(args: argparse.Namespace) -> int:
+    # J8: `review [<strategy>]` — retrospective trade-quality review. Bare = every accountable
+    # strategy + the cross-strategy realized aggregate; a named target reviews ONE. It is inherently
+    # on-box (enumerates <state>/composer/*, derives each runtime id from the install chain), so it
+    # RESOLVES the state root (CMP248 if unresolvable — the rim always threads it). Closed history is
+    # the in-process MCP seam; exit/leak enrichment is the live document's `events` section (served by
+    # the rim). NO events subprocess fallback: run offline, exits render "unavailable (no live channel)".
+    result = run_review(_resolve_state_dir(args.state_dir), args.target)
     if args.json:
         print(json.dumps(result.to_json(), indent=2, sort_keys=True))
     else:
@@ -791,10 +819,16 @@ def build_parser() -> argparse.ArgumentParser:
         help="Create + fund the strategy's wallet (MCP strategy_create_custom_strategy): preflights "
              "the balance, waits for ACTIVE, safe to re-run while funding settles.",
     )
-    p_fund.add_argument("target", help="A `composer deploy` staging dir, or a graph file (with -o).")
+    p_fund.add_argument("target", help="A `composer deploy` staging dir, or a graph file (with -o); "
+                                       "with --manual, a bare strategy NAME.")
     p_fund.add_argument("--budget", type=float, required=True,
                         help="Explicit USD to fund THIS strategy's wallet with (≥ $100). Never "
                              "derived or split — agree it with the user first.")
+    p_fund.add_argument("--manual", action="store_true",
+                        help="Fund a MANUAL strategy: a first-class wallet with NO graph/runtime, "
+                             "managed by the composer record system. Direct MCP position edits are "
+                             "the sanctioned path for this kind. Refuses if the name is already a "
+                             "managed (graph) strategy (CMP262).")
     p_fund.add_argument("-o", "--out", help="Staging dir (when target is a graph file, not a staged dir).")
     p_fund.add_argument("--state-dir", dest="state_dir",
                         help="Base senpi-state dir (rim passes it; else $SENPI_STATE_DIR; else refuse — never guessed from HOME).")
@@ -869,6 +903,23 @@ def build_parser() -> argparse.ArgumentParser:
     p_status.add_argument("--json", action="store_true", help="Emit the status as JSON.")
     p_status.set_defaults(func=_cmd_status)
 
+    p_review = sub.add_parser(
+        "review",
+        help="Retrospective trade-quality review: per-strategy closed-trade summary (count / win "
+             "rate / realized PnL), exit-reason distribution + leak findings from the box event log, "
+             "and recommendations judged against the graph's thesis. Bare = all strategies + the "
+             "cross-strategy realized aggregate.",
+    )
+    p_review.add_argument("target", nargs="?",
+                          help="A strategy NAME to review just one. Omit to sweep every accountable "
+                               "strategy (canonical + landed-legacy) and add the cross-strategy "
+                               "realized aggregate.")
+    p_review.add_argument("--state-dir", dest="state_dir",
+                          help="Base senpi-state dir (rim passes it; else $SENPI_STATE_DIR; else "
+                               "refuse — never guessed from HOME).")
+    p_review.add_argument("--json", action="store_true", help="Emit the review as JSON.")
+    p_review.set_defaults(func=_cmd_review)
+
     p_simulate = sub.add_parser(
         "simulate",
         help="Phase-A signal-timeline replay: drive the compiled scan(s) over historical candles "