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

package/dist/composer/examples/rotation_cross_sectional.graph.yaml

@@ -0,0 +1,389 @@
+# relative_value strategy (pairwise member) — machine-generated anchor (composer new).
+#
+# A FIXED pair [target, benchmark] compared cross-asset: N lookback returns (3d/7d/30d) feed
+# ONE two-output signed-net-score pure_fn. The benchmark leg is a REFERENCE only — always
+# fetched, never traded, never pruned (narrowing could drop it and break the comparison). The
+# fn LONGs the target when the benchmark runs ahead (target is cheap) and CLOSEs it when the
+# pair flips, with a hysteresis dead band and held-exclusion built in. Edit ONLY the pure_fn
+# body (the EDGE slot) to move this toward your edge; every intermediate state stays valid
+# (`composer check`).
+
+version: 1
+
+metadata:
+  archetype: relative_value
+  strategy: rotate_the_majors
+  generated:
+    by: "composer new"
+    content_hash: "1c3bbbe3999aa96dea3af04909293680fa9d46658245a525db6ee9bb7366f5cc"
+    structure_hash: "9efd6b0e577007a9db320ac103d5663a6f2d805794eab68726ff62757e193adc"
+  spec:
+    version: 2
+    archetype: relative_value
+    strategy: rotate_the_majors
+    thesis: "rotate into relative strength: rank the majors by weighted 3d/7d/30d return vs the basket mean, go long the strongest and fade the weakest within my slots; close a leg when its relative value conve..."
+    universe:
+      whitelist: ["BTC", "ETH", "SOL", "HYPE", "AVAX", "LINK"]
+      long_basket: []
+      short_basket: []
+      discover: false
+      dex: ""
+      name_prefix: ""
+      max_leverage_cap: 5.0
+      min_day_volume: 0.0
+    intervals: ["4h"]
+    max_positions: 3
+    dedup_seconds: 240
+    exit_preset: protected_wide
+    unmanaged: false
+    protection:
+      seeded_from: protected_wide
+      interval_seconds: 60
+      dsl_preset:
+        hard_timeout:
+          enabled: true
+          interval_in_minutes: 20160
+        weak_peak_cut:
+          enabled: false
+          interval_in_minutes: 240
+        dead_weight_cut:
+          enabled: false
+          interval_in_minutes: 480
+        phase1:
+          enabled: true
+          max_loss_pct: 25.0
+          retrace_threshold: 15
+          consecutive_breaches_required: 2
+        phase2:
+          enabled: true
+          tiers:
+            - trigger_pct: 15
+              lock_hw_pct: 0
+            - trigger_pct: 30
+              lock_hw_pct: 30
+            - trigger_pct: 60
+              lock_hw_pct: 55
+            - trigger_pct: 120
+              lock_hw_pct: 72
+            - trigger_pct: 250
+              lock_hw_pct: 85
+      guard_rails:
+        daily_loss_limit_pct: 15
+        max_consecutive_losses: 4
+        cooldown_seconds: 3600
+        drawdown_halt_pct: 25
+        drawdown_reset_on_day_rollover: false
+        per_asset_cooldown_seconds: 1800
+    risk:
+      margin_pct: 5.0
+      leverage: 3.0
+      drawdown_halt_pct: null
+      max_consecutive_losses: null
+      cooldown_seconds: null
+      max_entries_per_day: null
+    edge: "rotate into relative strength: rank the majors by weighted 3d/7d/30d return vs the basket mean, go long the strongest and fade the weakest within my slots; close a leg when its relative value converges back to the pack."
+    requires: []
+    exit_signals:
+      interval_seconds: 300
+      enter_threshold: 3.0
+      exit_threshold: 2.0
+      reentry_cooldown_seconds: 1800
+  # EDGE (verbatim, machine never interprets): "rotate into relative strength: rank the majors by weighted 3d/7d/30d return vs the basket mean, go long the strongest and fade the weakest within my slots; close a leg when its relative value converges back to the pack."
+
+nodes:
+  # 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).
+  - id: account
+    node: clearinghouse_state
+  # 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).
+  - id: positions
+    node: open_positions
+  # candle reads over the fixed basket (ranked cross-sectionally).
+  - id: candles
+    node: candles_fetch
+    with:
+      whitelist: ["BTC", "ETH", "SOL", "HYPE", "AVAX", "LINK"]
+      intervals: ["4h"]
+  # lookback returns at 4h (3d = 18 x 4h).
+  - id: ret_3d
+    node: pct_change
+    with:
+      lookback: 18
+      interval: "4h"
+  - id: ret_7d
+    node: pct_change
+    with:
+      lookback: 42
+      interval: "4h"
+  - id: ret_30d
+    node: pct_change
+    with:
+      lookback: 180
+      interval: "4h"
+  # ---------------------------------------------------------------
+  # EDGE (verbatim — the machine did NOT interpret this; encode it
+  # by editing the TODO slots on this scoring node):
+  #   rotate into relative strength: rank the majors by weighted 3d/7d/30d return vs the basket mean, go long the strongest and fade the weakest within my slots; close a leg when its relative value converges back to the pack.
+  # ---------------------------------------------------------------
+  # 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.
+  - id: score
+    kind: pure_fn
+    title: "cross-sectional relative strength: long the strongest, fade the weakest"
+    inputs:
+      - { name: ret_3d, type: feature_map, doc: "Per-asset 3d (18 x 4h) percent return." }
+      - { name: ret_7d, type: feature_map, doc: "Per-asset 7d (42 x 4h) percent return." }
+      - { name: ret_30d, type: feature_map, doc: "Per-asset 30d (180 x 4h) percent return." }
+      - { 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: 3.0, doc: "Relative strength to ENTER (top of the dead band); |RS| in return-percent units." }
+      - { name: exit_threshold, type: float, default: 2.0, doc: "Convergence band; a held name whose |RS| falls below it CLOSES (relative value realized)." }
+      - { name: w_3d, type: float, default: 1.0, doc: "Weight of the 3d window." }
+      - { name: w_7d, type: float, default: 2.0, doc: "Weight of the 7d window (longer = stronger)." }
+      - { name: w_30d, type: float, default: 3.0, doc: "Weight of the 30d window (longest = strongest)." }
+      - { name: signal_strength, type: float, default: 1.0, doc: "Per-signal score unit multiplier." }
+    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
+    tests:
+      - name: long_strongest_entry
+        inputs:
+          ret_3d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          ret_7d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          ret_30d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          positions: []
+        expect:
+          entry_scores:
+            AAA:
+              score: 8.0
+              direction: LONG
+              reasons: ["relative_strength"]
+            CCC:
+              score: 8.0
+              direction: SHORT
+              reasons: ["relative_weakness"]
+          exit_scores: {}
+      - name: short_weakest_entry
+        inputs:
+          ret_3d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          ret_7d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          ret_30d:
+            AAA: 8.0
+            BBB: 0.0
+            CCC: -8.0
+          positions: []
+        expect:
+          entry_scores:
+            AAA:
+              score: 8.0
+              direction: LONG
+              reasons: ["relative_strength"]
+            CCC:
+              score: 8.0
+              direction: SHORT
+              reasons: ["relative_weakness"]
+          exit_scores: {}
+      - name: dead_band_emits_nothing
+        inputs:
+          ret_3d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_7d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_30d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          positions: []
+        expect:
+          entry_scores: {}
+          exit_scores: {}
+      - name: converged_exit_when_held
+        inputs:
+          ret_3d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_7d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_30d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          positions:
+            - coin: AAA
+              direction: LONG
+              szi: 1.0
+              entry_px: 100.0
+              unrealized_pnl_pct: 2.0
+              margin_used: 10.0
+        expect:
+          entry_scores: {}
+          exit_scores:
+            AAA:
+              score: 1.0
+              direction: LONG
+              reasons: ["converged"]
+      - name: rank_flip_exit_when_held
+        inputs:
+          ret_3d:
+            AAA: -8.0
+            BBB: 0.0
+            CCC: 8.0
+          ret_7d:
+            AAA: -8.0
+            BBB: 0.0
+            CCC: 8.0
+          ret_30d:
+            AAA: -8.0
+            BBB: 0.0
+            CCC: 8.0
+          positions:
+            - coin: AAA
+              direction: LONG
+              szi: 1.0
+              entry_px: 100.0
+              unrealized_pnl_pct: 2.0
+              margin_used: 10.0
+        expect:
+          entry_scores:
+            CCC:
+              score: 8.0
+              direction: LONG
+              reasons: ["relative_strength"]
+          exit_scores:
+            AAA:
+              score: 8.0
+              direction: LONG
+              reasons: ["rank_flip"]
+      - name: flat_no_exit
+        inputs:
+          ret_3d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_7d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          ret_30d:
+            AAA: 1.0
+            BBB: 0.0
+            CCC: -1.0
+          positions: []
+        expect:
+          entry_scores: {}
+          exit_scores: {}
+  # ranker: rank the pool, fill up to 3 open slots (cardinality = 3).
+  - id: best
+    node: rank_pool_cap_to_open_slots
+    with:
+      max_slots: 3
+      min_score: 0
+  # entry emitter: build the scan() OPEN signal list.
+  - id: emit
+    node: signal_envelope
+    with:
+      margin_pct: 5.0
+      leverage: 3.0
+  # 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.
+  - id: close_emit
+    node: close_signal_envelope
+    with:
+      signal_type: "thesis_exit"
+
+edges:
+  # score -> rank -> emit
+  - { from: score.entry_scores, to: best.scores }
+  - { from: account.held, to: best.held }
+  # candles fan out to the lookback returns
+  - { from: candles.candles, to: ret_3d.candles }
+  - { from: candles.candles, to: ret_7d.candles }
+  - { from: candles.candles, to: ret_30d.candles }
+  # each lookback return -> its pure_fn input port
+  - { from: ret_3d.pct, to: score.ret_3d }
+  - { from: ret_7d.pct, to: score.ret_7d }
+  - { from: ret_30d.pct, to: score.ret_30d }
+  - { from: positions.positions, to: score.positions }
+  # entry tail: entry_scores -> rank -> emit
+  - { from: best.selected, to: emit.selected }
+  - { from: account.equity, to: emit.equity }
+  # exit tail: exit_scores -> close emitter (+ positions for direction)
+  - { from: score.exit_scores, to: close_emit.selected }
+  - { from: positions.positions, to: close_emit.positions }

package/dist/composer/generated/catalog.md

@@ -123,5 +123,6 @@ Edge data types (closed vocab). `composer describe <type>` gives producers/consu
 - **breakout** — directional range-break hard gate, fixed basket OR discovered universe.
 - **classifier** — a pure_fn direction classifier on a discovered/fixed universe.
 - **thesis_fund** — fixed long/short basket, direction fixed per leg, pure_fn confirmation.
-- **relative_value** — pairwise cross-asset compare [target, benchmark]; two-tail signal exit.
+- **relative_value** — pairwise [target, benchmark] OR cross_sectional rank-the-universe (long strong / fade weak).
 - **copy_trading** — follow a cohort (named wallets OR the leaderboard); copy their per-coin conviction.
+- **contrarian_fade** — fade an overextended move (RSI + price); crowd-gated (sm+funding) OR pure price.

package/dist/composer/registry/generate.py

@@ -397,8 +397,9 @@ def _catalog_archetypes() -> list[str]:
         "- **breakout** — directional range-break hard gate, fixed basket OR discovered universe.",
         "- **classifier** — a pure_fn direction classifier on a discovered/fixed universe.",
         "- **thesis_fund** — fixed long/short basket, direction fixed per leg, pure_fn confirmation.",
-        "- **relative_value** — pairwise cross-asset compare [target, benchmark]; two-tail signal exit.",
+        "- **relative_value** — pairwise [target, benchmark] OR cross_sectional rank-the-universe (long strong / fade weak).",
         "- **copy_trading** — follow a cohort (named wallets OR the leaderboard); copy their per-coin conviction.",
+        "- **contrarian_fade** — fade an overextended move (RSI + price); crowd-gated (sm+funding) OR pure price.",
     ]
 
 

package/dist/composer/validator/errors.py

@@ -139,6 +139,8 @@ ERROR_CODES: dict[str, str] = {
     "CMP258": "`composer new --from-spec` refused — the target graph has a generation marker but no readable `metadata.spec` block to rebuild the Answers from (a pre-F1 / legacy `answers:` graph, or a spec that was stripped/retyped); regenerate from the interview answers with `composer new <strategy> --archetype <A> …`.",
     # ---- H2 status live-read: the running runtime's scanner/protection/risk state is unreachable ----
     "CMP259": "The live runtime state (scanner cadence, per-position DSL protection, risk gates) could not be read from the gateway — it is unreachable, the runtime is not actually running, or it returned an unrecognized response; `composer status` still reports the lifecycle chain it CAN derive and marks the live section unavailable (never a silent partial). Check `openclaw senpi runtime list` / `openclaw gateway run`, then re-run.",
+    # ---- J3 manual strategy: `composer fund --manual` create-path collision ----
+    "CMP262": "`composer fund --manual` refused — the target name already exists as a MANAGED strategy (a graph.yaml record, a staged/ or releases/ tree, or a managed wallet.json). A manual strategy is a wallet with NO graph/runtime and cannot be created over a managed one; pick a different name, or manage the existing strategy as the graph strategy it already is.",
 }
 
 

package/dist/composer/verbs/__init__.py

@@ -29,6 +29,8 @@ from .group import (
     run_group_status,
 )
 from .install import CreateResult, InstallResult, install_target, run_install
+from .portfolio import PortfolioResult, run_portfolio_status
+from .review import ReviewResult, run_review
 from .simulate import SimulateResult, run_simulate
 from .smoke import SmokeError, run_smoke
 from .status import StatusResult, run_status
@@ -54,6 +56,10 @@ __all__ = [
     "run_group_status",
     "GroupCloseResult",
     "run_group_close",
+    "PortfolioResult",
+    "run_portfolio_status",
+    "ReviewResult",
+    "run_review",
     "StatusResult",
     "run_status",
     "UpdateResult",

package/dist/composer/verbs/_box.py

@@ -26,6 +26,7 @@ like ``install._default_create``.
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import subprocess
@@ -184,13 +185,86 @@ def _run_cli(args: list[str], timeout: int = 60) -> CliResult:
         return CliResult(-1, "", f"timed out after {timeout}s: {' '.join(argv)}")
 
 
-def default_list_runtimes() -> list[Runtime]:
-    """Production ListFn seam: ``openclaw senpi runtime list`` → parsed rows (empty on error —
-    the runtime registry simply isn't visible from a box without openclaw)."""
+# --------------------------------------------------------------------------- rim-served live doc
+
+# J9: eliminate the openclaw cold boot on the HOT READ paths. When the composer verbs run VIA THE
+# RIM (the exec CLI or the senpi_strategy gateway tool), the spawning TS process ALREADY has gateway
+# RPC access, so it fetches the system-state envelope + runtime-list rows IN-PROCESS (reusing the
+# same gateway RPCs `senpi state --json` / `senpi runtime list` use) and hands them to this Python
+# child as a temp JSON document via ``SENPI_LIVE_FILE``. The default read seams then serve from that
+# ONE document instead of each shelling a FRESH ``openclaw`` (a full CLI + plugins + OTel boot that
+# only RPCs back to the process family the rim started in — a pure loop). The subprocess shell-out
+# remains as the FALLBACK for a direct/offline invocation with no live-file handed down.
+#
+# The document is a versioned, extensible envelope: ``{version, system_state?, runtime_list?, ...}``
+# — J8's events read channel adds an ``events`` section without reshaping. An env var (not a CLI
+# flag) is the handoff: the read seams are wired as DEFAULT values deep inside the verb call trees
+# (portfolio → run_status → _attach_live → state_fn; close → _close_one → list_fn), so threading a
+# ``--live-file`` arg would mean plumbing it through every verb's run_* signature down to the seam
+# defaults; an env var is read at the point of use with ZERO signature changes, exactly like the
+# existing OPENCLAW_BIN / SENPI_STATE_DIR / SENPI_LOG_LEVEL reads in ``_run_cli``.
+
+def load_live_document() -> Optional[dict]:
+    """The rim-served live document named by ``SENPI_LIVE_FILE`` (a JSON
+    ``{version, system_state?, runtime_list?}`` envelope the TS rim fetched IN-PROCESS), or None
+    when no live-file was handed down (a direct/offline invocation → the seams shell openclaw)."""
+    path = os.environ.get("SENPI_LIVE_FILE", "").strip()
+    if not path:
+        return None
+    try:
+        with open(path, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+def _runtimes_from_live(section: Any) -> list[Runtime]:
+    """Map the live document's ``runtime_list`` section (gateway-native ``senpi.listRuntimes`` rows
+    ``{id, source, status, wallet}``) into the composer ``Runtime`` shape ``parse_runtime_list``
+    yields (``{name, wallet, source, status}``). A missing/errored section degrades to ``[]`` —
+    the SAME empty-on-error behavior the subprocess fallback has (the registry simply isn't
+    visible), so a rim-side fetch failure never masquerades as a populated list."""
+    if not isinstance(section, dict) or not section.get("ok"):
+        return []
+    out: list[Runtime] = []
+    for r in section.get("rows") or []:
+        if not isinstance(r, dict):
+            continue
+        out.append({
+            "name": r.get("id") or r.get("name"),
+            "wallet": r.get("wallet"),
+            "source": r.get("source"),
+            "status": r.get("status"),
+        })
+    return out
+
+
+def _shell_list_runtimes() -> list[Runtime]:
+    """Shell the FROZEN ``openclaw senpi runtime list`` consumer → parsed rows (empty on error)."""
     res = _run_cli(["openclaw", "senpi", "runtime", "list"])
     return parse_runtime_list(res.stdout) if res.ok else []
 
 
+def default_list_runtimes() -> list[Runtime]:
+    """Production ListFn seam: a rim-served live document (``SENPI_LIVE_FILE``) supplies the runtime
+    rows WITHOUT an openclaw boot (J9); the subprocess shell-out is the FALLBACK for a direct/offline
+    invocation with no live-file. Empty on error either way (the runtime registry simply isn't
+    visible from a box without openclaw)."""
+    doc = load_live_document()
+    if doc is not None and "runtime_list" in doc:
+        return _runtimes_from_live(doc.get("runtime_list"))
+    return _shell_list_runtimes()
+
+
+def list_runtimes_fresh() -> list[Runtime]:
+    """A FRESH runtime-list read that BYPASSES any rim-served live document (J9). The post-delete
+    teardown CONFIRM in close/update MUST NOT read a pre-run snapshot — the document was captured
+    BEFORE this Python process deleted the runtime, so serving the confirm from it would falsely see
+    the just-deleted runtime as still live (a spurious CMP221/CMP245). Always shells the consumer."""
+    return _shell_list_runtimes()
+
+
 def default_delete_runtime(runtime_id: str, wallet: str) -> CliResult:
     """Production DeleteFn seam: shell out to the FROZEN ``openclaw senpi runtime delete``
     consumer (senpi-commands.ts:110). ``--address`` scopes the delete to the bound wallet."""
@@ -353,6 +427,22 @@ def _pos_num(v) -> Optional[float]:
     return None
 
 
+def unwrap_positions_envelope(doc: Any) -> Any:
+    """Descend into a ``{success, data}`` MCP envelope BEFORE shape-parsing. The gateway wraps
+    ``strategy_get_clearinghouse_state`` as ``{success: true, data: {main, xyz}, meta: {...}}`` and
+    ``default_mcp_call`` returns that whole document, so the per-DEX buckets live one level down under
+    ``.data``. This mirrors the TS call path (client.ts::fetchClearingHouseStateOnce unwraps via
+    ``unwrapEnvelope`` at client.ts:791 BEFORE clearingHouseStateLooksParsable /
+    openPositionsFromClearingHouseState run) — those TS helpers never had the bug because their caller
+    unwraps first. Non-envelope shapes (an already-unwrapped flat list or top-level ``{main, xyz}``)
+    have no boolean ``success`` key and are returned unchanged, so existing shapes keep parsing."""
+    if not isinstance(doc, dict):
+        return doc
+    if not isinstance(doc.get("success"), bool) or "data" not in doc:
+        return doc
+    return doc.get("data")
+
+
 def clearinghouse_looks_parsable(state: dict) -> bool:
     """True if ``state`` is a recognizable strategy_get_clearinghouse_state response — either a
     flat ``positions``/``positionsList`` list, or per-DEX buckets carrying ``assetPositions`` /
@@ -432,6 +522,7 @@ def default_read_positions(wallet: str, mcp_fn: McpFn = default_mcp_call) -> Pos
         return PositionsResult(False, [], reason=f"MCP error reading positions ({e})")
     except Exception as e:  # noqa: BLE001 — a surprise transport fault must not crash the verb
         return PositionsResult(False, [], reason=f"could not read positions ({e})")
-    if not isinstance(raw, dict) or not clearinghouse_looks_parsable(raw):
+    state = unwrap_positions_envelope(raw)
+    if not isinstance(state, dict) or not clearinghouse_looks_parsable(state):
         return PositionsResult(False, [], reason="clearinghouse response shape not recognized")
-    return PositionsResult(True, parse_open_positions(raw))
+    return PositionsResult(True, parse_open_positions(state))

package/dist/composer/verbs/_layout.py

@@ -41,6 +41,17 @@ REBASELINE_DIR = "rebaseline"
 # legacy layout (read-side fallback only) -----------------------------------------------------
 LEGACY_STRATEGIES_DIR = "strategies"
 
+# strategy KIND (slice J3) --------------------------------------------------------------------
+# A strategy dir is either MANAGED (a graph + runtime under composer's lifecycle) or MANUAL (a
+# funded wallet with NO graph/runtime ever — direct MCP position edits are the sanctioned path).
+# The kind is persisted as an OPTIONAL ``"kind": "manual"`` marker INSIDE the canonical
+# ``wallet.json`` — the least-new-surface place: wallet.json already lives under this module's
+# path authority (``canonical_wallet_json``) and is the one artifact a manual strategy owns. Its
+# ABSENCE means MANAGED (back-compat: every pre-J3 wallet.json, and every managed strategy, has no
+# marker and is unchanged byte-for-byte). No sibling metadata file, no new path.
+KIND_MANAGED = "managed"
+KIND_MANUAL = "manual"
+
 # runtime-owned (frozen) ----------------------------------------------------------------------
 ARCHIVES_DIR = "archives"
 
@@ -141,6 +152,32 @@ def write_wallet_json(base_state_dir: str, strategy: str) -> Path:
     return canonical_wallet_json(base_state_dir, strategy)
 
 
+def wallet_kind(rec: Optional[dict]) -> str:
+    """The strategy KIND encoded in a wallet.json record (J3). Returns :data:`KIND_MANUAL` only for
+    an explicit ``"kind": "manual"`` marker; ANY other shape (no marker, a managed record, a
+    malformed rec) is :data:`KIND_MANAGED` — the back-compat default (absence = managed)."""
+    if isinstance(rec, dict) and str(rec.get("kind") or "").strip().lower() == KIND_MANUAL:
+        return KIND_MANUAL
+    return KIND_MANAGED
+
+
+def read_strategy_kind(base_state_dir: str, strategy: str) -> str:
+    """The persisted KIND of a strategy, read from its canonical/legacy wallet.json marker (J3).
+    A strategy with no wallet.json, or an unreadable one, is :data:`KIND_MANAGED` (a graph strategy
+    that has not been funded yet is managed; the marker only ever DISTINGUISHES manual). Never
+    throws — an unreadable marker degrades to managed rather than crash a sweep."""
+    import json  # local: _layout stays dependency-light (pure pathing + this tolerant read)
+
+    wj_path, _layout = resolve_wallet_json(base_state_dir, strategy)
+    if wj_path is None:
+        return KIND_MANAGED
+    try:
+        rec = json.loads(wj_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return KIND_MANAGED
+    return wallet_kind(rec)
+
+
 def iter_release_dirs(base_state_dir: str, strategy: str) -> list[tuple[Path, str]]:
     """Every LANDED release dir (one carrying an ``install.json``) for a strategy, across BOTH
     layouts, tagged ``"canonical"`` / ``"legacy"``. Canonical dirs are listed first so a caller that