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

package/dist/composer/verbs/portfolio.py

@@ -0,0 +1,650 @@
+"""portfolio — the CROSS-STRATEGY view of ``composer status`` with NO target (slice J2).
+
+``composer status <strategy>`` diagnoses ONE strategy (H2). ``composer status`` with NO target is
+the whole box's portfolio: every strategy the composer can account for (canonical layout + the
+legacy-layout installs the existing fallback finds), each with its lifecycle stage, wallet, on-box
+install/runtime state, and a per-position PROTECTION summary; PLUS the runtimes that are live or
+registered on the box but derivable from NO composer record (stranded/unmanaged — rendered WITH
+recovery text, never a bare "doesn't exist" beside a live runtime); PLUS a plain account-level /
+manual-position section (J3 will formalize a manual `kind`).
+
+This absorbs the ENGINE of the separately-versioned ``senpi-portfolio`` skill so that script can be
+deleted in a follow-up slice. It corrects that engine's three field-proven defects by CONSTRUCTION:
+
+  1. HOME-vs-gateway state root — there is no ``~/.openclaw/senpi-state`` guess anywhere; the state
+     root is threaded in by the rim (CMP248 refuses rather than guess). See composer/cli.py.
+  2. mis-parsed ratchet list → false "not yet armed" — protection is read from the BOX ENGINE's
+     ``getSystemState`` DSL positions (``currentTierIndex`` / ``floorPrice`` / ``slOrderId``), never
+     reconstructed from a second ``ratchet_stop_list`` call whose container key the live API changed.
+     ``_live.is_tier_armed`` derives "armed" from ``currentTierIndex`` directly.
+  3. fail-OPEN reassurance — unavailable data renders as "unavailable (reason)" here, never a
+     confident default. A running strategy whose gateway read failed says so (CMP259); a strategy
+     with no live read says "not read (not running)"; the manual section says why it is unavailable.
+
+SINGLE PRODUCER + ENGINE QUOTING (interim rule). DSL/protection state is QUOTED from the BOX ENGINE
+(``getSystemState`` via the H2 seam) and the render NAMES it as such. Where a backend record is also
+reachable through an EXISTING seam (the clearinghouse open-positions reader, ``_box.PositionsFn``)
+and DISAGREES with the box engine, a divergence warning naming BOTH sides is printed. The portfolio
+sweep does NOT fan that backend call out across the whole fleet by default (it is cred-gated and
+per-wallet); it is wired through an injectable ``positions_fn`` (tests inject it; per-strategy
+``composer status <strategy>`` is the live+backend detail surface). No NEW backend call is added.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from . import _box
+from ._box import ListFn, PositionsFn
+from ._layout import (
+    COMPOSER_DIR,
+    GRAPH_FILE,
+    KIND_MANAGED,
+    KIND_MANUAL,
+    LEGACY_STRATEGIES_DIR,
+    RELEASES_DIR,
+    STAGED_DIR,
+    WALLET_FILE,
+    iter_release_dirs,
+    resolve_wallet_json,
+    wallet_kind,
+)
+from ._live import (
+    LiveState,
+    SystemStateFn,
+    default_system_state,
+    human_tier,
+    is_tier_armed,
+    _pct,
+    _price,
+)
+from .status import (
+    InstallView,
+    StatusResult,
+    _all_managed_runtime_ids,
+    _read_registry_entries,
+    run_status,
+)
+
+# The name of the engine whose DSL/protection state the portfolio QUOTES (interim single-producer
+# rule until the dual-engine ownership contract lands). Printed in the render so an operator always
+# knows which producer the protection numbers came from.
+BOX_ENGINE = "box engine"
+
+# A wallet -> account/manual positions reader. Returns the account-level open positions NOT owned by
+# a composer strategy (or None when no such source is wired). J3 formalizes the manual `kind`; until
+# then the default is None (unavailable-with-reason), and a test/future caller injects a reader.
+ManualPositionsFn = Callable[[], Optional[list[dict]]]
+
+
+# --------------------------------------------------------------------------- position summary
+
+@dataclass
+class PortfolioPosition:
+    """One open position's compact PROTECTION summary, quoted from the box engine's live DSL state.
+    ``armed`` is derived from ``currentTierIndex`` directly (never a mis-parsed ratchet list)."""
+
+    asset: str
+    dex: Optional[str]
+    direction: Optional[str]
+    leverage: Optional[float]
+    roe: Optional[float]
+    armed: bool
+    tier_human: str
+    floor_price: Optional[float]
+    sl_order_id: Optional[object]
+
+    def to_json(self) -> dict:
+        return {
+            "asset": self.asset,
+            "dex": self.dex,
+            "direction": self.direction,
+            "leverage": self.leverage,
+            "roe": self.roe,
+            "armed": self.armed,
+            "tier": self.tier_human,
+            "floor_price": self.floor_price,
+            "sl_order_id": self.sl_order_id,
+        }
+
+    def render(self) -> str:
+        book = f"@{self.dex}" if self.dex and self.dex != "main" else ""
+        lev = f" {_numish(self.leverage)}x" if self.leverage is not None else ""
+        roe = f" ROE {_pct(self.roe, signed=True)}" if self.roe is not None else ""
+        if self.armed:
+            prot = f"ARMED {self.tier_human}, floor {_price(self.floor_price)}"
+        else:
+            prot = f"phase 1 ({self.tier_human}), floor {_price(self.floor_price)}"
+        sl = (f", exchange stop #{self.sl_order_id}" if self.sl_order_id not in (None, "")
+              else ", exchange stop not yet placed")
+        return f"{self.asset}{book} {self.direction or '?'}{lev}{roe} — {prot}{sl}"
+
+
+def _summarize_position(p: dict) -> PortfolioPosition:
+    tiers = p.get("tiers") or []
+    tier_idx = p.get("currentTierIndex")
+    return PortfolioPosition(
+        asset=str(p.get("asset") or "?"),
+        dex=p.get("dex"),
+        direction=p.get("direction"),
+        leverage=p.get("leverage"),
+        roe=p.get("currentROE"),
+        armed=is_tier_armed(p),
+        tier_human=human_tier(tier_idx, len(tiers)),
+        floor_price=p.get("floorPrice"),
+        sl_order_id=p.get("slOrderId"),
+    )
+
+
+# --------------------------------------------------------------------------- per-strategy row
+
+@dataclass
+class PortfolioStrategy:
+    """One strategy's portfolio row: lifecycle stage, wallet, on-box install/runtime state, and the
+    box-engine protection summary of its open positions (with any backend divergence warnings)."""
+
+    strategy: str
+    layout: str                     # "canonical" | "legacy"
+    position: str
+    next_verb: str
+    next_hint: str
+    wallet: Optional[str] = None
+    runtime_id: Optional[str] = None
+    runtime_state: str = "none"     # running | registered | landed | none
+    live_available: Optional[bool] = None   # None = not read (not running); True/False when read
+    live_reason: str = ""
+    positions: list[PortfolioPosition] = field(default_factory=list)
+    divergences: list[str] = field(default_factory=list)
+    split_warning: Optional[str] = None
+    # J3: the strategy KIND predicate. Managed rows carry protection; MANUAL rows have NO runtime,
+    # so they render a wallet + backend positions and no protection lines.
+    kind: str = KIND_MANAGED
+    manual_positions: list[dict] = field(default_factory=list)   # a MANUAL wallet's open positions
+    manual_reason: str = ""         # why a manual wallet's positions are unavailable (LOUD)
+
+    def to_json(self) -> dict:
+        out: dict = {
+            "strategy": self.strategy,
+            "layout": self.layout,
+            "kind": self.kind,
+            "position": self.position,
+            "next_verb": self.next_verb,
+            "next": self.next_hint,
+            "wallet": self.wallet,
+            "runtime_id": self.runtime_id,
+            "runtime_state": self.runtime_state,
+            "protection_source": BOX_ENGINE,
+            "live": (None if self.live_available is None
+                     else {"available": self.live_available, "reason": self.live_reason}),
+            "positions": [p.to_json() for p in self.positions],
+        }
+        if self.kind == KIND_MANUAL:
+            out["manual_positions"] = {
+                "available": not self.manual_reason,
+                "reason": self.manual_reason,
+                "positions": list(self.manual_positions),
+            }
+        if self.divergences:
+            out["divergences"] = list(self.divergences)
+        if self.split_warning:
+            out["split_warning"] = self.split_warning
+        return out
+
+    def render(self) -> list[str]:
+        if self.kind == KIND_MANUAL:
+            return self._render_manual()
+        wallet = self.wallet or "unbound"
+        rt = self.runtime_id or "-"
+        lines = [
+            f"  {self.strategy}  [{self.layout}]",
+            f"    stage      : {self.position}  (next: {self.next_verb})",
+            f"    wallet     : {wallet}",
+            f"    runtime    : {self.runtime_state}  ({rt})",
+        ]
+        # protection is QUOTED from the box engine; unavailability is LOUD, never a default.
+        if self.live_available is None:
+            lines.append("    protection : not read (runtime not running on this box)")
+        elif not self.live_available:
+            lines.append(f"    protection : UNAVAILABLE [CMP259] ({self.live_reason}) "
+                         f"— NOT assuming protected")
+        elif not self.positions:
+            lines.append("    protection : no open positions under DSL management")
+        else:
+            lines.append(f"    protection : {len(self.positions)} open position(s) "
+                         f"(quoted from the {BOX_ENGINE}):")
+            for p in self.positions:
+                lines.append(f"      - {p.render()}")
+        for d in self.divergences:
+            lines.append(f"    !! DIVERGENCE: {d}")
+        if self.split_warning:
+            lines.append(f"    !! {self.split_warning}")
+        return lines
+
+    def _render_manual(self) -> list[str]:
+        """A MANUAL strategy's row (J3): labeled as its own kind, NO runtime/protection lines (a
+        manual strategy has no runtime), and the wallet's open positions when the seam is wired."""
+        lines = [
+            f"  {self.strategy}  [manual]",
+            f"    kind       : manual (wallet under composer record; NO runtime — by design)",
+            f"    wallet     : {self.wallet or 'unbound'}",
+            "    runtime    : none (manual strategies have no runtime; direct MCP position edits "
+            "are the sanctioned path)",
+        ]
+        if self.manual_reason:
+            lines.append(f"    positions  : not read ({self.manual_reason})")
+        elif not self.manual_positions:
+            lines.append("    positions  : none open on this wallet")
+        else:
+            lines.append(f"    positions  : {len(self.manual_positions)} open on this wallet:")
+            for p in self.manual_positions:
+                asset = p.get("coin") or p.get("asset") or "?"
+                dex = p.get("dex")
+                book = f"@{dex}" if dex and dex != "main" else ""
+                sz = p.get("szi") if p.get("szi") is not None else p.get("size")
+                lines.append(f"      - {asset}{book} size={sz}")
+        return lines
+
+
+# --------------------------------------------------------------------------- stranded runtimes
+
+@dataclass
+class StrandedRuntime:
+    """A runtime that is LIVE (in ``runtime list``) and/or REGISTERED (installed_runtimes.json) but
+    derivable from NO composer install record — rendered WITH recovery text so status never reports
+    "doesn't exist" beside a runtime the box is actually running (field triage #2)."""
+
+    runtime_id: str
+    live: bool
+    registered: bool
+    wallet: Optional[str] = None
+    status: Optional[str] = None
+
+    @property
+    def source(self) -> str:
+        if self.live and self.registered:
+            return "live + registered"
+        if self.live:
+            return "live (runtime list)"
+        return "registered (installed_runtimes.json)"
+
+    @property
+    def recovery(self) -> str:
+        return (
+            "no composer graph produced this runtime. It is real on the box — do NOT treat it as "
+            "absent. Either ADOPT it (author a graph.yaml for this strategy, `composer deploy` + "
+            "`composer install` onto the SAME wallet to bring it under management) or TEAR IT DOWN "
+            f"(`openclaw senpi runtime delete --id {self.runtime_id}`"
+            + (f" --address {self.wallet}" if self.wallet else "")
+            + "). `composer close` only handles composer-managed strategies."
+        )
+
+    def to_json(self) -> dict:
+        return {
+            "runtime_id": self.runtime_id,
+            "live": self.live,
+            "registered": self.registered,
+            "source": self.source,
+            "wallet": self.wallet,
+            "status": self.status,
+            "recovery": self.recovery,
+        }
+
+
+# --------------------------------------------------------------------------- portfolio result
+
+@dataclass
+class PortfolioResult:
+    base_state_dir: str
+    strategies: list[PortfolioStrategy] = field(default_factory=list)
+    stranded_runtimes: list[StrandedRuntime] = field(default_factory=list)
+    manual_available: bool = False
+    manual_reason: str = ""
+    manual_positions: list[dict] = field(default_factory=list)
+
+    def to_json(self) -> dict:
+        return {
+            "verb": "status",
+            "scope": "portfolio",
+            "state_dir": self.base_state_dir,
+            "protection_source": BOX_ENGINE,
+            "strategy_count": len(self.strategies),
+            "strategies": [s.to_json() for s in self.strategies],
+            "stranded_runtimes": [r.to_json() for r in self.stranded_runtimes],
+            "manual_positions": {
+                "available": self.manual_available,
+                "reason": self.manual_reason,
+                "positions": list(self.manual_positions),
+            },
+        }
+
+    def render(self) -> str:
+        lines = [
+            f"portfolio status  (state: {self.base_state_dir})",
+            f"protection quoted from the {BOX_ENGINE} (getSystemState); unavailable data is shown "
+            f"as such, never assumed protected.",
+            "",
+            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())
+        # stranded / unmanaged runtimes — WITH recovery text (never a bare "doesn't exist").
+        lines.append("")
+        if self.stranded_runtimes:
+            lines.append(f"stranded runtimes ({len(self.stranded_runtimes)}) — live/registered on "
+                         f"the box, NO composer record:")
+            for r in self.stranded_runtimes:
+                lines.append(f"  - {r.runtime_id}  [{r.source}]"
+                             + (f"  wallet={r.wallet}" if r.wallet else "")
+                             + (f"  status={r.status}" if r.status else ""))
+                lines.append(f"      recovery: {r.recovery}")
+        else:
+            lines.append("stranded runtimes: none (every live/registered runtime maps to a composer "
+                         "record)")
+        # manual / account-level positions — plain section, LOUD when unavailable (J3 formalizes it).
+        lines.append("")
+        lines.append("account-level / manual positions (not attributed to any strategy):")
+        if not self.manual_available:
+            lines.append(f"  unavailable ({self.manual_reason})")
+        elif not self.manual_positions:
+            lines.append("  none")
+        else:
+            for p in self.manual_positions:
+                asset = p.get("asset") or p.get("coin") or "?"
+                direction = p.get("direction") or ""
+                dex = p.get("dex")
+                book = f"@{dex}" if dex and dex != "main" else ""
+                sz = p.get("szi") if p.get("szi") is not None else p.get("size")
+                lines.append(f"  - {asset}{book} {direction} size={sz}")
+        return "\n".join(lines) + "\n"
+
+
+# --------------------------------------------------------------------------- enumeration
+
+def _has_canonical_artifacts(strategy_dir: Path) -> bool:
+    return (
+        (strategy_dir / GRAPH_FILE).is_file()
+        or (strategy_dir / STAGED_DIR).is_dir()
+        or (strategy_dir / RELEASES_DIR).is_dir()
+    )
+
+
+def _is_manual_dir(strategy_dir: Path) -> bool:
+    """J3: a MANUAL strategy dir — a canonical dir owning ONLY a ``wallet.json`` marked
+    ``kind: manual`` (no graph/staged/releases). Enumerated so a manual strategy is accountable in
+    the portfolio despite carrying none of the graph-lifecycle artifacts."""
+    wj = strategy_dir / WALLET_FILE
+    if not wj.is_file():
+        return False
+    try:
+        import json as _json
+        rec = _json.loads(wj.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    return wallet_kind(rec) == KIND_MANUAL
+
+
+def enumerate_strategies(state_dir: Path) -> list[str]:
+    """Every strategy name the composer can account for: canonical dirs under ``<state>/composer``
+    carrying a graph.yaml / staged/ / releases/ (managed) OR a ``kind: manual`` wallet.json (J3
+    manual), PLUS legacy strategies under ``<state>/strategies`` with at least one LANDED release
+    (the existing read-side fallback). Sorted, de-duped."""
+    names: set[str] = set()
+    comp = state_dir / COMPOSER_DIR
+    if comp.is_dir():
+        for child in comp.iterdir():
+            if child.is_dir() and (_has_canonical_artifacts(child) or _is_manual_dir(child)):
+                names.add(child.name)
+    legacy = state_dir / LEGACY_STRATEGIES_DIR
+    if legacy.is_dir():
+        for child in legacy.iterdir():
+            if child.is_dir() and iter_release_dirs(str(state_dir), child.name):
+                names.add(child.name)
+    return sorted(names)
+
+
+# --------------------------------------------------------------------------- build one row
+
+def _resolve_wallet(state_dir: Path, strategy: str, current: Optional[InstallView]) -> Optional[str]:
+    if current is not None and current.wallet:
+        return current.wallet
+    wj_path, _layout = resolve_wallet_json(str(state_dir), strategy)
+    if wj_path is not None:
+        try:
+            data = json.loads(wj_path.read_text(encoding="utf-8"))
+            w = data.get("wallet")
+            return str(w) if w else None
+        except (OSError, json.JSONDecodeError):
+            return None
+    return None
+
+
+def _cross_check_divergences(box_positions: list[PortfolioPosition], wallet: str,
+                             positions_fn: PositionsFn) -> list[str]:
+    """Cross-check the BOX ENGINE's protected positions against the backend clearinghouse (an
+    EXISTING seam). Names BOTH sides on any disagreement; fails LOUD when the backend is unverifiable
+    (never silently assumes agreement)."""
+    res = positions_fn(wallet)
+    if not res.verified:
+        return [f"backend cross-check unavailable ({res.reason}) — the {BOX_ENGINE} protection above "
+                f"is UNCONFIRMED against the exchange clearinghouse"]
+    box_assets = {p.asset.upper() for p in box_positions}
+    backend_assets = {str(r.get("coin") or "").upper() for r in res.positions if r.get("coin")}
+    out: list[str] = []
+    for asset in sorted(box_assets - backend_assets):
+        out.append(f"{asset}: {BOX_ENGINE} reports it OPEN + under protection, but the backend "
+                   f"clearinghouse shows NO open {asset} position (protection state may be stale / "
+                   f"the position already closed)")
+    for asset in sorted(backend_assets - box_assets):
+        out.append(f"{asset}: the backend clearinghouse shows an OPEN {asset} position that the "
+                   f"{BOX_ENGINE} is NOT protecting on this wallet (manual/unmanaged position)")
+    return out
+
+
+def _effective_install(st: StatusResult) -> Optional[InstallView]:
+    """The install a portfolio row speaks for: the deployed-current one if run_status marked it,
+    else the RUNNING install, else the first landed one. (An installed-only strategy with no
+    canonical graph.yaml has no ``is_current`` hash to match, so run_status leaves current_install
+    None even while a runtime is running — the portfolio must still speak for that running install.)"""
+    if st.current_install is not None:
+        return st.current_install
+    running = next((i for i in st.installs if i.running), None)
+    if running is not None:
+        return running
+    return st.installs[0] if st.installs else None
+
+
+def _build_strategy_row(state_dir: Path, strategy: str, st: StatusResult,
+                        state_fn: SystemStateFn,
+                        positions_fn: Optional[PositionsFn]) -> PortfolioStrategy:
+    current = _effective_install(st)
+    layout = current.layout if current is not None else (
+        "canonical" if (state_dir / COMPOSER_DIR / strategy).is_dir() else "legacy"
+    )
+    runtime_state = current.state if current is not None else "none"
+    runtime_id = current.runtime_id if current is not None else None
+    wallet = _resolve_wallet(state_dir, strategy, current)
+
+    row = PortfolioStrategy(
+        strategy=strategy,
+        layout=layout,
+        position=st.position,
+        next_verb=st.next_verb,
+        next_hint=st.next_hint,
+        wallet=wallet,
+        runtime_id=runtime_id,
+        runtime_state=runtime_state,
+        split_warning=st.split_warning,
+        kind=st.kind,
+    )
+
+    # J3: a MANUAL strategy has NO runtime — there is no box-engine protection to quote. Attribute
+    # its wallet's open positions via the EXISTING clearinghouse seam when wired (default None => not
+    # read, LOUD), then return — none of the managed live/protection logic below applies.
+    if st.kind == KIND_MANUAL:
+        if positions_fn is not None and wallet:
+            try:
+                res = positions_fn(wallet)
+            except Exception as e:  # noqa: BLE001 — a seam fault must not break the sweep
+                row.manual_reason = f"positions read raised ({e})"
+            else:
+                if res.verified:
+                    row.manual_positions = list(res.positions)
+                else:
+                    row.manual_reason = res.reason or "positions unverifiable"
+        else:
+            row.manual_reason = "not read (no positions source wired at the portfolio level)"
+        return row
+
+    # PROTECTION, quoted from the box engine. run_status attaches live only for the deployed-current
+    # install; for a running install it didn't mark current, fetch it here (same seam). None => not
+    # running (not read). available False => gateway read failed (CMP259) — LOUD, never assumed.
+    live = st.live
+    if live is None and current is not None and current.running and current.runtime_id:
+        try:
+            live = state_fn(current.runtime_id)
+        except Exception as e:  # noqa: BLE001 — the seam should not throw; never crash the sweep
+            live = LiveState(False, reason=f"live read raised ({e})", runtime_id=current.runtime_id)
+
+    if live is None:
+        row.live_available = None
+    elif not live.available:
+        row.live_available = False
+        row.live_reason = live.reason
+    else:
+        row.live_available = True
+        row.positions = [_summarize_position(p) for p in live.positions]
+        # divergence cross-check against the backend, only if a seam is wired + a wallet is known.
+        if positions_fn is not None and wallet:
+            try:
+                row.divergences = _cross_check_divergences(row.positions, wallet, positions_fn)
+            except Exception as e:  # noqa: BLE001 — a cross-check fault must not break the sweep
+                row.divergences = [f"backend cross-check raised ({e}) — protection UNCONFIRMED"]
+    return row
+
+
+# --------------------------------------------------------------------------- stranded derivation
+
+def _derive_stranded(state_dir: Path, runtimes: list[dict]) -> list[StrandedRuntime]:
+    """Runtimes LIVE (runtime list) and/or REGISTERED (installed_runtimes.json) with no composer
+    install record. Cross-checks BOTH the live registry AND the on-disk registry before concluding a
+    runtime is unmanaged (field triage #2)."""
+    managed = _all_managed_runtime_ids(state_dir)
+    live_by_id: dict[str, dict] = {}
+    for r in runtimes:
+        rid = r.get("name")
+        if rid:
+            live_by_id.setdefault(str(rid), r)
+    registered_ids = {str(e.get("id")) for e in _read_registry_entries(state_dir) if e.get("id")}
+
+    out: list[StrandedRuntime] = []
+    for rid in sorted(set(live_by_id) | registered_ids):
+        if rid in managed:
+            continue
+        live_row = live_by_id.get(rid)
+        out.append(StrandedRuntime(
+            runtime_id=rid,
+            live=live_row is not None,
+            registered=rid in registered_ids,
+            wallet=(live_row.get("wallet") if live_row else None),
+            status=(live_row.get("status") if live_row else None),
+        ))
+    return out
+
+
+# --------------------------------------------------------------------------- entry point
+
+def run_portfolio_status(
+    base_state_dir: str,
+    *,
+    list_fn: ListFn = _box.default_list_runtimes,
+    state_fn: SystemStateFn = default_system_state,
+    positions_fn: Optional[PositionsFn] = None,
+    manual_positions_fn: Optional[ManualPositionsFn] = None,
+) -> PortfolioResult:
+    """The cross-strategy portfolio view (bare ``composer status``). Enumerates every accountable
+    strategy (reusing the per-strategy ``run_status`` derivation — the single producer), lists
+    stranded/unmanaged runtimes WITH recovery text, and renders a plain manual-positions section.
+
+    ``positions_fn`` (default None) opts INTO the backend divergence cross-check via the existing
+    clearinghouse seam; the default sweep does not fan it out across the fleet. ``manual_positions_fn``
+    (default None) supplies account-level positions; without it the section is unavailable-with-reason
+    (J3 formalizes the manual kind)."""
+    state_dir = Path(base_state_dir)
+    result = PortfolioResult(base_state_dir=str(state_dir))
+
+    # ONE runtime-list read, shared by the per-strategy rows and the stranded derivation.
+    try:
+        runtimes = list_fn()
+    except Exception:  # noqa: BLE001 — a listing fault degrades to no live/stranded info, not a crash
+        runtimes = []
+    shared_list: ListFn = lambda: runtimes  # noqa: E731
+
+    # J9: the live system-state seam is MEMOIZED across the whole sweep, keyed by runtime id, so a
+    # bare status with N strategies consumes ONE pre-fetched state document and never fetches per row
+    # (the rim serves ALL rows from a single ``senpi.getSystemState`` it fetched once — see
+    # _live.default_system_state). The injectable seam is preserved verbatim for tests; this only
+    # collapses repeat reads of the SAME runtime.
+    _state_cache: dict = {}
+
+    def shared_state_fn(rid, _fn=state_fn, _cache=_state_cache):
+        if rid not in _cache:
+            _cache[rid] = _fn(rid)
+        return _cache[rid]
+
+    for strategy in enumerate_strategies(state_dir):
+        st = run_status(strategy, state_dir=str(state_dir),
+                        list_fn=shared_list, state_fn=shared_state_fn)
+        result.strategies.append(
+            _build_strategy_row(state_dir, strategy, st, shared_state_fn, positions_fn))
+
+    result.stranded_runtimes = _derive_stranded(state_dir, runtimes)
+
+    # manual / account-level positions — plain, LOUD when unavailable.
+    if manual_positions_fn is None:
+        result.manual_available = False
+        result.manual_reason = (
+            "no account-position source is wired at the portfolio level — the box engine only "
+            "tracks strategy-attributed positions. J3 will formalize a manual `kind`."
+        )
+    else:
+        try:
+            positions = manual_positions_fn()
+        except Exception as e:  # noqa: BLE001
+            result.manual_available = False
+            result.manual_reason = f"account-position read raised ({e})"
+        else:
+            if positions is None:
+                result.manual_available = False
+                result.manual_reason = "account-position source returned no data"
+            else:
+                # attribute-out anything a strategy already tracks (by asset), leaving the manual
+                # set. J3: this now also attributes positions on MANUAL-strategy wallets to those
+                # strategies (via the same clearinghouse seam), so a manual strategy's own positions
+                # are NOT double-counted in the unattributed account-level section.
+                attributed = {p.asset.upper()
+                              for s in result.strategies for p in s.positions}
+                attributed |= {
+                    str(mp.get("coin") or mp.get("asset") or "").upper()
+                    for s in result.strategies for mp in s.manual_positions
+                    if (mp.get("coin") or mp.get("asset"))
+                }
+                result.manual_available = True
+                result.manual_positions = [
+                    p for p in positions
+                    if str(p.get("asset") or p.get("coin") or "").upper() not in attributed
+                ]
+    return result
+
+
+def _numish(v) -> str:
+    if isinstance(v, bool):
+        return str(v)
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v)